Table of Contents
Copyright � 2002-2003 Gareth Cronin, Auckland, New Zealand, garethc@veryquick.org
2003
Table of Contents
List of Tables
Very Quick Wiki or "VQWiki" for short is a WikiWikiWeb engine clone.
This book is intended for installers and administrators of VQWiki. It may also be of use to end users as it provides more detail than the start pages of the Wiki itself about some of the advanced functions of VQWiki. It is a work in progress - contributions and corrections are more than welcome.
This content is authored as DocBook[1] - the open XML standard for technical writing - and is rendered to presentation formats using the XSL from the DocBook Open Repository Project[2]
[1] DocBook at Oasis http://www.oasis-open.org/docbook/
[2] DocBook Open Repository http://docbook.sourceforge.net/
Conventions Used in this Manual.� As with any manual, there are a number of abbreviations you should be aware of.
Installation seems like a sensible place to start. We'll go through installation on one of the most widely used application servers for non-commercial applications - Apache (Jakarta) Tomcat.[3]
First-time installation should be very simple on any application server. Upgrading from an earlier versions of VQWiki is a little more difficult, so we'll cover that later.
VQWiki is designed to be a "drop and run" application. When you download VQWiki from a website, it will be available as a single "Web Archive File" or "WAR" for short. Most application servers (including Tomcat) are capable of automatically deploying an application directly from a WAR
We will assume that you have installed Tomcat on a Windows machine in the directory c:\Tomcat and that it is running with the default stand-alone port 8080. We will also assume that the VQWiki WAR file is named vqwiki-2.0.war. Finally, we will assume that you have a Web browser available on the installation machine. Of course, your Tomcat directory and the name of the WAR file may be slightly different, but I'm sure you can substitute where necessary.
Shut down Tomcat
Move the downloaded WAR file into c:/Tomcat/webapps
Start Tomcat
Browse to http://localhost:8080/vqwiki-2.0
That's it!
VQWiki is now running with the default flat-file persistence and the default options. You will now probably want to customise some of the options, so we'll go through how to do this after an explanation of the basic Wiki concepts.
On the opening screen, you'll see a list of links - one to this guide, another to StartingPoints and another to TextFormattingRules. When you choose StartingPoints or TextFormattingRules, you will find yourself at a Wiki topic. If you have never browsed to a Wiki topic on your installation before, you will be given a password. This password is the administration password. Memorize it!. If you miss the password, or you forget it, see the section on password recovery later in this guide.
This chapter will touch on the major mechanisms available in VQWiki. The more complex mechanisms receive their own chapters later on.
Editing, Linking and WikiNames.� Any topic in a Wiki may be edited. The user clicks the "Edit" link at the top or bottom of the page, makes changes and clicks the "Save" button. They are then redirected back to the saved topic. Wiki has its own markup language, VQWiki has a subset and a series of extensions of the original markup. The markup includes a system for "automagic" linking, where certain formats are recognised as hyperlinks and presented as such. The most important of these is the WikiName. Words in "CamelCaps" become links to topics as named by the WikiName. VQWiki also allows wiki-naming by surrounding a word in back-ticks.
Searching.� The user can click the "Search" link from any topic page to reach the search page. The search page provides a text field for text entry and performs a full-text search based on this text, returning a list of topics where the text is found. If more than one search term is entered, the topics are ordered by relevance, i.e. the topics where all of the search terms were found are shown first. A search can also be performed by clicking on the title of any topic - this searches for the topic name itself.
Reserved Topics.� Some topic names are reserved for redirection to Wiki features. For example, the topic WikiSearch will send the user to the search page.
Username Cookies.� WikiWikiWeb was never meant to be a secure, rights-based system, therefore the support for auditing is very simplistic (a security extension is on the drawing board for future versions). By using the SetUsername reserved topic, a user can set a username for themselves. This sends a cookie to their browser to identify them in the future. Usernames are important for display in RecentChanges and for email notification.
RecentChanges.� The RecentChanges reserved topic displays a list of recently altered topics, together with the date and time it was altered and the username of the person who altered it (or their IP address if they did not set a username).
File Upload and Attachment.� When writing Wiki topics it is often useful to be able to attach a file of some kind to the topic. A user can click the "Attach" link on any topic and be presented with a file upload page. Attached files can be referred to by a linking syntax (e.g. "att:myfile.txt"). VQWiki has its own MIME type mapping that can be customised to suit installations.
Email Notification.�Users who have set usernames can register an email address and subscribe to topics. They are then notified by email when a topic they are interested in is changed.
Virtual Wikis.�The last part of the VQWiki URL ("jsp" by default) is the name of a "virtual wiki". It is possible to set up as many virtual wikis as you like, each one with its own completely independent contents.
Templates.� Topics can be saved as templates. The template can then be appended to any topic. This allows for the creation of standard forms for input, such as requirements documents or contact details.
Versioning.� Every change to a topic is written to a separate versioning copy. This acts as disaster-recovery and anti-vandalism backup and supports a "diff" facility, where the actual changes made to a topic can be identified. The history browser, accessible through the "History" link on the menu bar of each topic shows all the versions that exist.
Read Only Topics.�Topics such as StartingPoints can be designated as read-only by the administrator.
Default Topics.�Several topics are created by default the first time VQWiki is run, or when a new virtual wiki is accessed. These are TextFormattingRules (a description of the markup available by default), FritzTextFormattingRules (a description of the markup available in the other shipped lexer) and StartingPoints (a default start page).
Table of Contents
The admin console is protected by a password that is shown to the first person to browse to a Wiki topic after installation. The admin username is "admin". If you have lost your password see the section on password recovery below.
At the bottom of any Wiki topic you will see the version of VQWiki you are using and an "Admin" link. Click this link.
After you have logged in (username "admin"), you will find yourself looking at a list of text fields and check boxes, each representing some customisable feature of the Wiki. We'll present a table of these settings and refer you on to those that need their own chapters for further explanation.
Table�4.1.�Admin Console Settings
| Editing lock time-out | The number of minutes that a user can edit a topic for exclusively. After this time out, another user may begin to edit the topic, and should this occur, the user whose edit timed-out will have to redo their changes. |
| Number of days of RecentChanges | The number of days back from the present day to display changes made in the RecentChanges list |
| Maximum number of backlinks | At the bottom of every page a list of links to topics that link to the current topic is displayed. If the topic is mentioned often, this list can grow very large. The maximum backlink limit keeps this list to the specified number. If the number is exceeded, a "..." appears after the list. A user can always check on all the backlinks by clicking on the topic title to perform a search on the title term. |
| Automatic index interval | In the default flat-file mode, the search index is updated every time a topic is altered, this picks up any additions to topics, however it does not account for removal of terms that have been deleted from topic text. A periodic sweep of the text needs to be made to account for deletions. This interval is the amount of time between sweeps. 24 hours should really be sufficient, due to the fact that Wiki is by nature additive rather than subtractive. |
| New line breaks | This controls how many HTML breaks are inserted for every new line in the edited text. The default is 2, but some people prefer one line to equal one line, in which case this can be set to 1. |
| Use versioning | When this is switched off, version backup and diff is not available. This is only recommended where disk space is a real problem. |
| Allow HTML | When this option is switched on, HTML markup will not be ignored, it will be output as HTML. |
| Allow back-tick WikiNames | When this option is on, back-tick wiki-naming is allowed. With the option off, only traditional CamelCaps naming can be used. |
| Force the setting of username | When this option is on, users must set a username before they are allowed to edit topics |
| Format-Lexer, Layout-Lexer and Link-Lexer | These are set as fully qualified Java class names. The format lexer is the class responsible for tokenizing the user input and formatting it approprtiately - e.g. bold, and italics, the layout lexer takes care of lists and tables. The link lexer is responsible for the automagic linking as described earlier. It is possible to write a single lexer that does both, in which case the link lexer should be set to "null'. More details on this can be found later in this manual. |
| Upload directory | This can either be a relative or an absolute path. If it is relative, it will be created relative to the {installdir}. Ensure that if you are using Windows, you specify the path with Unix-style forward slashes ("/"), not the DOS-style backslashes. The directory specified by the path will be used to store file upload attachments. |
| File upload size limit | This is the maximum allowable file-size in KB, any larger files will be rejected on upload. |
| Attachment type | There are two ways to deliver attachments to users. "Inline" will ask the browser to open the file itself, e.g. with a plug-in as for Adobe Acrobat. It will do this in a new window. "Attachment" asks the browser to show a download prompt immediately. It really depends on how you use attachments as to which is preferable for your users. It is also very much up to the browser how it deals with the requests, so behaviour will differ across different browsers. |
| File-system directory | In flat-file mode, this is where the files for the wiki topics will be stored. |
| SMTP host, username and password | This is the SMTP host name or IP address for the server that will handle outgoing email for topic change notifications. The username and password can be left blank for non-authenticating SMTP servers. |
| Reply address | This is the address that will appear in the reply-to field for Wiki email notifications. |
| Persistence | This is where the persistence mode can be set - either the default "Flat-File", or "Database" to use a MySQL database as the back end. If you select "Database", you will be presented with further fields in which to enter the JDBC database driver name, the database name and a user and password. VQWiki ships with the MM MySQL driver and its name will be the default value. See the chapter on MySQL for more information on setting this up. |
Following the settings are a number of other functions.
Table�4.2.�Admin Console Functions
| Refresh Search Index | This forces the flat-file mode search indexer to run. As mentioned earlier, the indexer is run automatically at the interval specified above. |
| Purge Deleted Topics | This will delete any topics that contain only the word "delete". |
| Clear Edit Lock on Topic | To use this, enter a topic name and click the "Go" button, any lock that is held on the topic will be cleared. |
| Read-only Topics | Use this section to add and remove topics that should be read-only |
| Add virtual wiki | Entering a new virtual wiki name and clicking add will register the virtual wiki of that name. Note that a servlet mapping must be added to the web-app descriptor as well. This is covered later in this manual. |
If you misplace the admin password, you can force VQWiki to generate a new one and display it to you on the first topic browsed to (as with initial installation). Use a text editor to edit the {installdir}/WEB-INF/classes/vqwiki.properties file (or another location if you have overridden the default) and change the key-value pair that reads firstuse=false to firstuse=true. Restart the application context or the application server and browse to StartingPoints. You will be shown the new admin password.
The Admin Console writes to a properties file called vqwiki.properties. This file along with the other configuration files will be by default in {installdir}/WEB-INF/classes. The files must be in the root of the classpath becuase they are searched for using the ClassLoader. The VQWiki environment also has hard-coded default values for the properties to ensure that it will always start regardless of whether or not a properties file is available. Here's a summary of all the resource and property files:
Table�5.1.�Configuration Files
| File | Purpose/Contents |
|---|---|
| vqwiki.properties | System settings |
| ApplicationResources.properties | Locale-specific language strings. This includes the mail messages to be sent on email notification of topic changes |
| linking.properties | Mapping of automagic link syntax to URLs. The link system is extensible, e.g. you can add an entry to make cvs:MyFile link to your local WebCVS. |
| mime.types | MIME type mapping by file extension for attachment delivery to browsers. This is actually just the standard Apache mapping. |
| log4j.properties | The Apache Jakarta Log4J properties file. This controls the logging output level. It should be set to WARN, but I sometimes forget and leave it set to DEBUG before releasing. |
There are some application servers that don't like files being written to when they are resources. There is also the case that you may want to keep your properties file intact between Wiki upgrades. In these instances you can set a location for the properties file by adding an environment entry named "propertiesFile" to the web-app descriptor for your Wiki context, e.g.:
<Context path="/vqwiki" docBase="vqwiki-2.0" debug="0" > <!-- the rest of your context information --> <env-entry> <description>VQWiki propertiesFile</description> <env-entry-name>propertiesFile</env-entry-name> <env-entry-value>c:/myproperties</env-entry-value> <env-entry-type>java.lang.String</env-entry-type> </env-entry> </Context>
The custom logo image feature works as follows:
By default, we use {installdir}/images/logo.jpg. If the user specifies the URL of an alternate image in the deployment metadata, that image will be used instead. In this case, a "Powered by VQWiki" image will be displayed on the footer of all pages that use the custom logo.
E.g., in Tomcat server.xml, it would look like this (note the override attribute):
<Context path="" docBase="vqwiki-classic" debug="0" > <env-entry> <description>logoImageName</description> <env-entry-name>logoImageName</env-entry-name> <env-entry-value>/images/tomcat-power.png</env-entry-value> <env-entry-type>java.lang.String</env-entry-type> </env-entry> </Context>
or
<Context path="/vqwiki/mikewiki" docBase="vqwiki-classic" debug="0" > <Environment name="logoImageName" type="java.lang.String" value="http://images.sourceforge.net/head_bg_new.gif" override="false"/> </Context>
The index page and admin console still display the VQWiki logo, as always.
VQWiki's major goal is to be as easy to deploy as possible, i.e. drop the WAR, start the server. It is for this reason that the default file system exists. The principles are very simple, but so is WikiWikiWeb, so it works:
By default, the file-system is set up in the user's home directory, in a sub-directory named "vqwiki". This location can be changed from the admin console.
Every topic gets written to one text file named as the topic with a "txt" extension
Versioning gets written to files with a timestamp in the filename in a versions sub-directory
Locking is maintained by the creation of files named as the topic with a "lock" extension
Usernames, subscriptions and recent changes are serialized via JSX[4] to XML files
If you require higher performance than you would expect from the above system, that's where the MySQL database mode as described in the next chapter comes in.
Using MySQL as a back end turns VQWiki into a very quick Wiki indeed. The development goal is still drop-and-go, so VQWiki will build its own tables when you first connect it to a database: no scripts to run (except for creating the database of course - it has to connect to something).
The default settings are for a database called "vqwiki" with a user called "vqwiki" with password "vqwiki". If you were to use those settings, and the MySQL server is running on the same machine as the web container, the following two statements will prepare the database:
create database vqwiki;
grant all on *.* to vqwiki@localhost identified by 'vqwiki';
The easiest way to do this is to find your MySQL binary - on Windows this is called "mysql.exe" and is in your MySQL bin directory. On Linux it's just called "mysql" and is usually in /usr/bin. If you run the mysql binary, you'll be presented with the mysql prompt, at which you can just copy and paste in the statements above.
Obviously, you may need to change the hostname from localhost to something else if you are running MySQL on a different machine to the one running the database, or if you have set MySQL to bind to an address other than the localhost loopback, e.g. if MySQL is bound to a network card.
When a user clicks the edit link, an exclusive lock is set on the topic they are editing. While this lock is present, any other users attempting to edit the topic will receive an error message asking them to try again later. This prevents conflicts occuring where one user inadvertently overwriters another user's changes.
If a user spends longer editing a topic than specified in the edit-lock timeout setting, the lock will be revoked when another user edits that topic. If the user who originally obtained the lock attempts to save, they will receive an error message telling them that their lock has expired. It is then up to user whose lock expired to merge the changes they took too long over into the new user's changes, once that user has finished editing their version.
Of course, if a user edits beyond their timeout and noone else tries to edit the same topic during that time, they may continue to save as normal. On an average size Wiki, this is almost always the case.
The administrator can unlock a topic manually by going to the "WikiLockList" topic. This topic displays a list of current locks with an "unlock" link beside each one. If you have not already logged in as an administrator, you will be prompted to log in upon clicking an unlock link.
As mentioned earlier, the format lexer is the class responsible for tokenizing the user input and formatting it appropriately - e.g. bold, italics, lists and tables. The link lexer is responsible for the automagic linking as described earlier. It is possible to write a single lexer that does both, in which case the link lexer should be set to "null'.
VQWiki is distributed with three default lexers: vqwiki.lex.FormatLex and vqwiki.lex.LinkLex are designed to work together and should be adequate for most purposes.
A third lexer vqwiki.lex.FritzLex (written by Fritz Freiheit) does not require a separate link lexer, so the link lexer should be set to "null" in the admin console to use it. This lexer supports a wider range of heading styles than the default lexers.
The lexers that come with VQWiki are generating using the JLex[5] tool. However, you can write your lexer in any way you choose - so long as it implements the vqwiki.lex.Lexer interface.
From version 2.4.0 onwards, VQWiki supports external lexers. These lexers are triggered from the standard lexers using special markup. As an example, VQWiki is supplied with vqwiki.lex.JavaLex which uses the java2html[6] library to format Java source code into pretty HTML. To see it in action, try entering the following into a Wiki topic:
[<java>] class Test{ public void test(); } [</java>]
You should see neatly formatted Java source code. The special tag format asks VQWiki to process all the text inside the tags using the class named as the value for "java" in the {installdir}/WEB-INF/classes/externallex.properties file. The default entry in this file is: java=vqwiki.lex.JavaLex.
To write your own external lexer, write a class that implements vqwiki.lex.ExternalLex interface (it's only one method) and put an entry with an appropriate tag name in the externallex.properties file.
E.g. you might write a class called vqwiki.mylexers.CLex for formatting C code. You could then make an entry in the properties file of the form c=vqwiki.mylexers.CLex. Anything between the tags [<c>][</c>] would then be passed to the process( String text ) method in the class vqwiki.mylexers.CLex.
By default, VQWiki supports entries to make reference to the original C2 WikiWikiWeb, the Meatball Wiki and individual Microsoft Knowledge Base articles. The shorthand for these all take the form prefix:detail
You can add new external links by editing the file {installdir}/WEB-INF/linking.properties. A comment in the file explains the straightforward syntax. In the case of the C2 Wiki, the entry is c2=http://c2.com/cgi/wiki?${url}. The ${url} keyword is expanded to whatever the user puts after the colon when they create the link, e.g if they put c2:StartingPoints, ${url} will be expanded to "StartingPoints" creating the complete URL http://c2.com/cgi/wiki?StartingPoints
This system is limited to external lexer installations at the moment. It will be extended to enable installation of more advanced plugins as work on pluggability is continued.
If you wish to distribute an external lexer as a plugin, it is possible to package it as one zip with a single XML file to describe the external lex properties entry. If the zip is placed in the {wikihome}/plugins, its file structure will be automatically unzipped into the {installdir} on startup. If the plugin filename is "myplugin", then a file called myplugin.xml should be placed inside the zip in the WEB-INF/classes path.
The myplugin.xml file can contain an entry of the form
<plugin><external-lex tag="mytag" class="mypackage.MyLexClass"/></plugin>
This entry will be translated into an entry in externallex.properties. So the entire zip file structure for myplugin.zip should look like:
WEB-INF/classes/myplugin.xml
WEB-INF/classes/mypackage/MyLexClass
This is an experimental feature at the moment, but hopefully it will become a part of the wider VQWiki architecture. VQWiki has a class loader that will load any class files found in the {wikihome}/plugins directory that implement the vqwiki.TopicListener interface. This interface only fires one event at the moment: TopicSavedEvent. It will fire this whenever a topic is saved.
This plugin system will eventually be extended to cover topic deletion, user registration etc to make it easier to write pluggable extensions, avoid the hassle of merging code while it is changing and break down the current somewhat monolithic Wiki distribution so VQWiki can be custom assembled to meet requirements.