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

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

Add qwiki-source-path to qwiki spiffy config example

File size: 13.9 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(qwiki-source-path "/path/to/the/checkout/directory")
187
188;; Ensure this is an absolute path, if you are using Chicken 4.1 or earlier
189(root-path "/var/www/html/qwiki")
190
191;; Pass all requests to non-existent files through qwiki:
192(vhost-map `((".*" . ,(lambda (continue)
193                        (parameterize ((handle-not-found qwiki-handler)
194                                       (handle-directory qwiki-handler)
195                                       (index-files '()))
196                           (continue))))))
197
198(start-server)
199</enscript>
200
201When you run this, your qwiki installation should be available at
202http://localhost:8080
203
204==== Customizing Qwiki
205
206===== qwiki
207
208These parameters are exported by the {{qwiki}} module.
209
210<parameter>(qwiki-css-file [FILE])</parameter>
211
212Set an optional CSS file to use for styling the wiki.  {{FILE}} should
213be a string, which is parsed into an uri-common object by the
214{{uri-reference}} procedure.  This URI should be relative to the
215docroot.  Defaults to {{#f}}.
216
217<parameter>(qwiki-title [TITLE])</parameter>
218
219Set an optional global {{TITLE}} or "name" for the wiki.  This will
220appear on every page in the browser's titlebar to inform the user that
221he's on a page of this particular wiki. Defaults to {{#f}}.
222
223<parameter>(qwiki-source-path [DIRECTORY])</parameter>
224
225The directory where qwiki expects a checkout of the repository that
226holds the wiki pages.  When running the installation procedure, it
227will make this checkout.
228
229The value defaults to the environment variable {{QWIKI_SOURCE_PATH}}
230if set. Otherwise it will default to {{"/tmp/qwiki"}}.
231
232<parameter>(qwiki-web-path [DIRECTORY])</parameter>
233
234The directory where qwiki will write its generated and cached HTML files to.
235Defaults to the environment variable {{QWIKI_WEB_PATH}} if set, otherwise
236will default to {{"/var/www"}}.
237
238This variable is only for when qwiki is called from the commandline or
239through the post-commit hook.  It is ''ignored'' when running qwiki
240through {{qwiki-handler}} inside Spiffy.  In that case it will just
241use Spiffy's {{root-path}}.
242
243<parameter>(qwiki-docroot [DIRECTORY])</parameter>
244
245In case you want qwiki be accessible underneath a subdirectory of
246spiffy, you can use this.  (it's unsure whether this even works and
247whether it will stay)
248
249<parameter>(qwiki-base-uri [URI])</parameter>
250
251The URI (an [[uri-common]] object) under which this wiki is
252available.  All internal links will use this as their base URI.
253Defaults to {{/}}.
254
255<parameter>(qwiki-output-driver [TRANSFORMATION-RULES])</parameter>
256
257This defaults to {{qwiki-html-transformation-rules}} from the
258{{qwiki-sxml}} module.  It can be changed to
259{{qwiki-LaTeX-transformation-rules}} or
260{{qwiki-Texinfo-transformation-rules}} when generating offline
261documentation.
262
263<parameter>(qwiki-extensions [EXTENSIONS])</parameter>
264
265This parameter can be extended to add transformation rule extensions
266to the output driver.  Defaults to the empty list.
267
268A transformation rule is simply a ruleset accepted by {{pre-post-order*}}.
269
270<parameter>(qwiki-update-handlers [HANDLERS])</parameter>
271
272This parameter can be extended to add update callbacks which will be
273invoked when a wiki page was updated. Defaults to the empty list.
274
275An update hook is a procedure that accepts a path to the wiki page (a
276list of path components) and the sxml which represents the new
277contents.
278
279<parameter>(qwiki-delete-handlers [HANDLERS])</parameter>
280
281This parameter can be extended to add update callbacks which will be
282invoked when a wiki page was removed. Defaults to the empty list.
283
284<parameter>(blocked-ip-addresses-file [PATH])</parameter>
285
286A path relative to the qwiki checkout which points to a file
287containing IP addresses to be blocked, one address per line.
288Useful for combating spam.
289
290Defaults to {{"edit-deny"}}.
291
292<parameter>(qwiki-current-file [PATH])</parameter>
293
294Not to be touched in the configuration; this is a run-time parameter
295used to indicate the current wiki file being processed.  Useful for
296use in transformation rules.
297
298===== qwiki-svn
299
300These parameters are exported by the {{qwiki-svn}} module.
301
302<parameter>(qwiki-repos-uri [URI-STRING])</parameter>
303
304The URI to the subversion repository.  Defaults to #f, so you must
305configure this!
306
307<parameter>(qwiki-repos-username [USERNAME])</parameter>
308
309The username for commits done from the wiki interface when the user
310chooses not to authenticate.  Default: {{"anonymous"}}
311
312<parameter>(qwiki-repos-password [PASSWORD])</parameter>
313
314The password for the {{qwiki-repos-username}} user.
315Default: {{""}}
316
317===== qwiki-search
318
319These parameters are exported by the {{qwiki-search}} module.
320
321<parameter>(search-server-uri [URI])</parameter>
322
323Defaults to whatever the environment variable {{QWIKI_SEARCH_URI}}
324holds if it is set, or else {{"http://admin:admin@localhost:1978"}},
325which is the default estraier URI.
326
327
328===== qwiki-menu
329
330These parameters are exported by the {{qwiki-menu}} module.
331
332<parameter>(menu-file [PATH])</parameter>
333
334If not {{#f}}, this file will contain (in wiki syntax) the contents
335of the menu which is rendered on all wiki pages.  Should be relative
336to the wiki checkout directory.  Defaults to {{"/menu"}}.
337
338
339===== qwiki-install
340
341<procedure>(qwiki-install!)</procedure>
342
343Performs the steps for installing qwiki.  It uses the parameters
344{{qwiki-repos-uri}}, {{qwiki-source-path}} and {{qwiki-web-path}} and
345considers their values are valid ones.
346
347This procedure is to be used by installation scripts.
348
349
350===== qwiki-post-commit-hook
351
352<procedure>(qwiki-post-commit-hook!)</procedure>
353
354Executes the required steps after a commit is performed. It uses the
355parameters {{qwiki-repos-uri}}, {{qwiki-source-path}} and considers
356their values are valid ones.
357
358This procedure is to be used by Subversion post-commit scripts.
359
360
361=== Changelog
362
363* trunk - Use {{finish-response-body}} from intarweb so that in case we start using chunking we get proper output.
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-2012, 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.