chickadee » qwiki

Outdated egg!

This is an egg for CHICKEN 4, the unsupported old release. You're almost certainly looking for the CHICKEN 5 version of this egg, if it exists.

If it does not exist, there may be equivalent functionality provided by another egg; have a look at the egg index. Otherwise, please consider porting this egg to the current version of CHICKEN.

qwiki

Description

A fast and light-weight wiki.

Author

Ivan Raikov and Peter Bex

Requirements

Documentation

qwiki is the "quick wiki". It is a lightweight wiki which uses sxml for internal wiki page representation. This makes it relatively easy to extend.

In the future we also hope to support multiple storage backends but right now subversion is the only implementation of that.

How to set it up

Set up hyper-estraier

If you want the wiki to be searchable (via the optional qwiki-search module), you should start by setting up a Hyper Estraier server. This is as simple as navigating to the directory under which you want the full text database to be created and entering the following commands:

 # estmaster init estraierdb
 # estmaster start estraierdb

This creates the db and sets the server running.

Later, if you are happy with the setup and the wiki is working properly, you can add this line to your startup scripts:

 estmaster start -bg /path/to/estraierdb

The -bg switch puts it into daemon mode (and makes it quiet).

Create a subversion repository

You should first create a subversion repository, if you don't already have one. Then, make a script called post-commit which you put in repo's hooks directory. This script should invoke the qwiki-post-commit-hook! procedure from the qwiki-post-commit-hook module. Here's an example (path/to/your/repo/hooks/post-commit):

#! /usr/bin/csi -s

(use qwiki qwiki-svn qwiki-post-commit-hook)

;; the URI for the subversion repository from where a copy can be
;; checked out
(qwiki-repos-uri "file:///path/to/the/repository/directory")

;; the path to where the checkout of the repository will be stored
(qwiki-source-path "/path/to/the/checkout/directory")

;; the path used by the web server to serve wiki pages
(qwiki-web-path "/path/to/web/server/documents/directory")

;; If you don't want to use these extensions, you can remove the lines
(search-install!)
(menu-install!)

(qwiki-post-commit-hook!)

If you prefer, you can delay setting up the post-commit hook until after you got the wiki up and running (this is a good idea if people will be committing to the repository while you are setting this up).

You can also call the post-commit scheme script (like the example above) from any other script you want to use as the actual post-commit script. You can also call arbitrary other scripts from the Scheme script, of course.

Don't forget to make the script executable!

Deploy qwiki

Now you are ready to run the qwiki installation procedure which will create an initial checkout, process all files to make a cached HTML file for each wiki page and populate the search index.

The best way to do that is by creating a script which sets the required parameters and calls qwiki-install!. Here's a simple example:

(use qwiki qwiki-install qwiki-svn)

;; the URI for the subversion repository from where a copy can be
;; checked out
(qwiki-repos-uri "file:///path/to/the/repository/directory")

;; the path to where the checkout of the repository will be stored
(qwiki-source-path "/path/to/the/checkout/directory")

;; the path used by the web server to serve wiki pages
(qwiki-web-path "/path/to/web/server/documents/directory")

;; install qwiki
(qwiki-install!)

Here's a more complex example:

(use qwiki qwiki-install qwiki-search qwiki-menu qwiki-svn)

;; Try to read the svnwiki user password
(handle-exceptions
 exn
 (begin
   (with-output-to-port (current-error-port)
     (lambda ()
       (print "Could not read the password file for the SVN user.  Aborting.")))
   (exit 1))
 (qwiki-repos-password
  (with-input-from-file "the-password-file" read-line)))

(search-install!)
(menu-install!)
(qwiki-repos-username "the-wiki-user")
(qwiki-css-file "/wiki.css")
(qwiki-title "The wiki")

(qwiki-repos-uri "file:///var/svn/")
(qwiki-source-path "/tmp/qwiki")
(qwiki-web-path "/var/www/spiffy/wiki")

(qwiki-install!)

The values for qwiki-source-path and qwiki-web-path should not overlap.

The exact directory locations are up to you, of course, but they will have to match the locations of the post-commit-hook. You can also set the search URI location through the QWIKI_SEARCH_URI environment variable if you changed the default admin account or want it to use some other location than localhost.

Now, you can run this script to get started.

Create a spiffy configuration

Currently qwiki can only run under Spiffy, so you will either have to run spiffy as your main webserver, or proxy all requests for the wiki to it.

(use spiffy qwiki qwiki-search qwiki-menu qwiki-svn)

;; If you don't want these extensions, remove them from this script
(search-install!)
(menu-install!)

(qwiki-repos-uri "file:///path/to/repos")
(qwiki-source-path "/path/to/the/checkout/directory")

;; Ensure this is an absolute path, if you are using Chicken 4.1 or earlier
(root-path "/var/www/html/qwiki")

;; Pass all requests to non-existent files through qwiki:
(vhost-map `((".*" . ,(lambda (continue)
                        (parameterize ((handle-not-found qwiki-handler)
				       (handle-directory qwiki-handler)
				       (index-files '()))
                           (continue))))))

(start-server)

When you run this, your qwiki installation should be available at http://localhost:8080

Customizing Qwiki

qwiki

These parameters are exported by the qwiki module.

qwiki-css-file #!optional FILEparameter

Set an optional CSS file to use for styling the wiki. FILE should be a string, which is parsed into an uri-common object by the uri-reference procedure. This URI should be relative to the docroot. Defaults to #f.

qwiki-title #!optional TITLEparameter

Set an optional global TITLE or "name" for the wiki. This will appear on every page in the browser's titlebar to inform the user that he's on a page of this particular wiki. Defaults to #f.

qwiki-source-path #!optional DIRECTORYparameter

The directory where qwiki expects a checkout of the repository that holds the wiki pages. When running the installation procedure, it will make this checkout.

The value defaults to the environment variable QWIKI_SOURCE_PATH if set. Otherwise it will default to "/tmp/qwiki".

qwiki-web-path #!optional DIRECTORYparameter

The directory where qwiki will write its generated and cached HTML files to. Defaults to the environment variable QWIKI_WEB_PATH if set, otherwise will default to "/var/www".

This variable is only for when qwiki is called from the commandline or through the post-commit hook. It is ignored when running qwiki through qwiki-handler inside Spiffy. In that case it will just use Spiffy's root-path.

qwiki-docroot #!optional DIRECTORYparameter

In case you want qwiki be accessible underneath a subdirectory of spiffy, you can use this. (it's unsure whether this even works and whether it will stay)

qwiki-base-uri #!optional URIparameter

The URI (an uri-common object) under which this wiki is available. All internal links will use this as their base URI. Defaults to /.

qwiki-output-driver #!optional TRANSFORMATION-RULESparameter

This defaults to qwiki-html-transformation-rules from the qwiki-sxml module. In principle, this allows you to generate different formats of output (like LaTeX, Texinfo or others), but the alternate implementations that used to exist have bitrotted, so they're no longer shipped.

qwiki-extensions #!optional EXTENSIONSparameter

This parameter can be extended to add transformation rule extensions to the output driver. Defaults to the empty list.

A transformation rule is simply a ruleset accepted by pre-post-order*.

qwiki-update-handlers #!optional HANDLERSparameter

This parameter can be extended to add update callbacks which will be invoked when a wiki page was updated. Defaults to the empty list.

An update hook is a procedure that accepts a path to the wiki page (a list of path components) and the sxml which represents the new contents.

qwiki-delete-handlers #!optional HANDLERSparameter

This parameter can be extended to add update callbacks which will be invoked when a wiki page was removed. Defaults to the empty list.

blocked-ip-addresses-file #!optional PATHparameter

A path relative to the qwiki checkout which points to a file containing IP addresses to be blocked, one address per line. Useful for combating spam.

Defaults to "edit-deny".

qwiki-current-file #!optional PATHparameter

Not to be touched in the configuration; this is a run-time parameter used to indicate the current wiki file being processed. Useful for use in transformation rules.

qwiki-svn

These parameters are exported by the qwiki-svn module.

qwiki-repos-uri #!optional URI-STRINGparameter

The URI to the subversion repository. Defaults to #f, so you must configure this!

qwiki-repos-username #!optional USERNAMEparameter

The username for commits done from the wiki interface when the user chooses not to authenticate. Default: "anonymous"

qwiki-repos-password #!optional PASSWORDparameter

The password for the qwiki-repos-username user. Default: ""

These parameters are exported by the qwiki-search module.

search-server-uri #!optional URIparameter

Defaults to whatever the environment variable QWIKI_SEARCH_URI holds if it is set, or else "http://admin:admin@localhost:1978", which is the default estraier URI.

qwiki-menu

These parameters are exported by the qwiki-menu module.

menu-file #!optional PATHparameter

If not #f, this file will contain (in wiki syntax) the contents of the menu which is rendered on all wiki pages. Should be relative to the wiki checkout directory. Defaults to "/menu".

qwiki-install
qwiki-install!procedure

Performs the steps for installing qwiki. It uses the parameters qwiki-repos-uri, qwiki-source-path and qwiki-web-path and considers their values are valid ones.

This procedure is to be used by installation scripts.

qwiki-post-commit-hook
qwiki-post-commit-hook!procedure

Executes the required steps after a commit is performed. It uses the parameters qwiki-repos-uri, qwiki-source-path and considers their values are valid ones.

This procedure is to be used by Subversion post-commit scripts.

Changelog

License

 Copyright (c) 2009-2017, Ivan Raikov and Peter Bex
 All rights reserved.
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are
 met:
 
 Redistributions of source code must retain the above copyright
 notice, this list of conditions and the following disclaimer.
 
 Redistributions in binary form must reproduce the above copyright
 notice, this list of conditions and the following disclaimer in the
 documentation and/or other materials provided with the distribution.
 
 Neither the name of the author nor the names of its contributors may
 be used to endorse or promote products derived from this software
 without specific prior written permission.
 
 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
 FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE
 COPYRIGHT HOLDERS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
 INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
 (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
 SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
 HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
 STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
 ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 OF THE POSSIBILITY OF SUCH DAMAGE.

Contents »