VQWiki Documentation

for release 2.8.1

Martijn van der Kleijn

NijiSoft

Gareth Cronin

Cronin Solutions

Marcello Teodori

JUG Milano

Tim Howland

Watchdog Systems, LLC

VQWiki version 2.8.1 VeryQuickWiki can be downloaded from http://www.vqwiki.org/ . This application is a work in progress - contributions and corrections are welcome and may be sent to:

Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".

February 1st, 2006

Abstract

This book contains the complete documentation set for the VQWiki project. The VQWiki project is licensed under the LGPL and can be downloaded from http://www.vqwiki.org/.


Preface
1. About VQWiki
Introduction
Conventions Used in this Manual
Features
VQWiki History
Changes for version 2.8.1
Changes for version 2.8
Changes for version 2.7 UNRELEASED
Changes for version 2.7.91
Changes for version 2.7.9
Changes for version 2.7.8
Changes for version 2.7.7
Changes for version 2.7.6
Changes for version 2.7.6
Changes for version 2.7.5
Changes for version 2.7.2
Changes for version 2.7.1
Changes for version 2.7.0
Changes for version 2.6.4
Changes for version 2.6.3
Changes for version 2.6.2
Changes for version 2.6.1
Changes for version 2.6.0
Changes for version 2.5.5
Changes for version 2.5.4
Changes for version 2.5.3
Changes for version 2.5.2
Changes for version 2.5.1
Changes for version 2.5.0
Changes for version 2.5.0 RC 2
Changes for version 2.5.0 RC 1
Changes for version 2.5.0 BETA 3
Changes for version 2.5.0 BETA 2
Changes for version 2.5.0 BETA 1
Changes for version 2.4.0
Changes for version 2.4.0 RC 3
Changes for version 2.4.0 RC 2
Changes for version 2.4.0 RC 1
Changes for version 2.4.0 BETA 2
Changes for version 2.4.0 BETA 1
Changes for version 2.3.6
Changes for version 2.3.5
Changes for version 2.3.4
Changes for version 2.3.3
Changes for version 2.3.2
Changes for version 2.3.1
Changes for version 2.3
Changes for version 2.2.1
Changes for version 2.2
Changes for version 2.1
Changes for version 2.0 BETA 2
Changes for version 2.0 BETA 1
Changes for version 1.8.2
Changes for version 1.8.1
Changes for version 1.8.0
Changes for version 1.7.0
Changes for version 1.6.3
Changes for version 1.6.2
Changes for version 1.6.1
Changes for version 1.6
Changes for version 1.5
Changes for version 1.4
Contributors
License
About This Documentation
Document Structure
Getting the latest version of this document
Where to go for help
2. Administrator's Guide
Wiki Functions
Editing
WikiNames
Linking
Searching
Reserved Topics
Username Cookies
RecentChanges
File Upload and Attachment
Email Notification
Templates
Versioning
Read Only Topics
Default Topics
Installation
Supported Systems
Known Configurations
Quick start
Basic Installation
Upgrading
Persistence - The Default File-System
Migrating to database-backed persistence
Configuration Settings
Admin Console Settings
Parameters in web.xml
Parameters in properties files
Lexers
Administrative Tasks
Creating Virtual Wikis
Integrating with LDAP
Maintenance Tasks
Troubleshooting
Panic Reset
Administrator Password Reset
Clearing Locks
Customizing Look and Feel
Using a Custom Logo
Customizing Page Layouts
Plugins
Installing Plugins
Developing Plugins
Security Issues and Workarounds
VQWiki File Storage Issues
Restricting Access
3. User's Guide
What is a Wiki?
VQWiki Basics
Editing a topic
Basic Formatting and Markup tags
Creating a new topic
Attaching a file or graphic to a topic
Looking at a topic's history
Reverting a topic to a previous version
Advanced VQWiki
Special Pages
Templates
Advanced Formatting
Using Plugins
Deleting a Topic
Elements of Wiki Style
A. GNU Free Documentation License
PREAMBLE
APPLICABILITY AND DEFINITIONS
VERBATIM COPYING
COPYING IN QUANTITY
MODIFICATIONS
COMBINING DOCUMENTS
COLLECTIONS OF DOCUMENTS
AGGREGATION WITH INDEPENDENT WORKS
TRANSLATION
TERMINATION
FUTURE REVISIONS OF THIS LICENSE
ADDENDUM: How to use this License for your documents
B. GNU Lesser General Public License
Preamble
TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION
Section 0
Section 1
Section 2
Section 3
Section 4
Section 5
Section 6
Section 7
Section 8
Section 9
Section 10
Section 11
Section 12
Section 13
Section 14
NO WARRANTY Section 15
Section 16
How to Apply These Terms to Your New Libraries

Preface

This manual is intended to assist with installing, administering, customizing, and using VQWiki software. This document is a work in progress. Please send corrections or suggestions to support@vqwiki.org or Tim Howland

This manual is presented using 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]

Chapter 1. About VQWiki

Introduction

A Wiki is software that allows users to create and edit Web page content using a Web browser. As a collaboration tool, Wiki's are unusual in that they allow the organization of content to be edited in addition to the content itself. The first Wiki engine was developed in 1995 by Ward Cunningham. Since then many Wiki engines, such as VQWiki, have been developed. The etymology of Wiki is described here. You can learn more about Wiki usage at http://www.wiki.org/wiki.cgi?WhatIsWiki.

"Very Quick Wiki" or "VQWiki" is a Wiki engine written using JSPs and servlets and is designed to run on Tomcat or any servlet container that supports Java Servlet 2.3 and JSP 1.2 specifications. Gareth Cronin is the original developer of the VQWiki. Thanks to the contributions of many, VQWiki has undergone numerous improvements. VQWiki supports hyperlinks, topic or text-based searching, email notifications, and utilizes a simple but powerful text syntax for creating topics and editing their content.

Conventions Used in this Manual

As with any manual, there are a number of abbreviations you should be aware of as you read:

Table 1.1. Conventions

{TOMCAT_HOME} The directory where Tomcat (or other application server) is installed.
{wikiurl} The base URL for accessing VQWiki, e.g. http://localhost:8080/vqwiki . With a WAR name of "vqwiki-2.8.1.war", the default local URL for Tomcat will be http://localhost:8080/vqwiki-2.8.1
{wikihome} The wiki file system home. For users of the Microsoft Windows operating system, the wiki file system home is located at C:\WINDOWS\SYSTEM32\CONFIG\systemprofile\wiki


Features

Very Quick Wiki is a WikiWikiWeb clone based on Java Server Pages. It's goal is to be as lightweight but as functional as possible. It is deployed by dropping a single war file into any J2EE web container without any extra installation processes. It offers the standard features found in most Wiki systems, as well as many other capabilities. Features include:

  • Support for multiple independent virtual wikis

  • Localized versions available in Italian, Spanish, German, Swedish, Norwegian, Polish, French, Dutch, and English

  • Built-in full-text search and indexing

  • RSS Feeds for recent changes

  • Email alerts for page notification

  • Filesystem storage for smaller systems, database storage for larger wikis

  • LDAP integration for authentication in corporate environments

  • Custom functionality through plugins and lexers

VQWiki History

For questions or comments, please create an issue on JIRA of type "Support Request" on JIRA

Changes for version 2.8.1

See Release Notes on JIRA

Changes for version 2.8

See Release Notes on JIRA

Changes for version 2.7 UNRELEASED

Bug

  • Improved removal of lockfiles

  • Fixed minor screen layout issue

  • Fixed issue with vqwiki.properties that could not be found

Improvement / Patch

  • Using StyleSheet topic as CSS instead of vqwiki.css

  • ExFormatLex has now support for macros (replace keywords with html snippets)

  • Editor jsp reworked

  • Table of contents for headlines (default: switched off)

  • Added resource message admin.caption.openextlinkinnewindow

  • Added property openExtLinkInNewWindow

  • Added logging if lock file couldn't be deleted

  • New version of fileupload (commons-fileupload 1.1 / commons-io 1.2)

  • New QuickHelp special topic for edit screen

  • Added russian translation

  • Updated german translation

  • Added strikethrough support that doesn't conflict with horizontal line

  • Added new WikiHelp default topics

  • Improved default LeftMenu and TopArea contents

  • Removed vqwiki.css file deprecated, replaced by StyleSheet topic

  • Removed source code is no longer included in war file, please get it from the repository

Changes for version 2.7.91

Bug

  • Attach link in top menu bar was broken

  • Attach functionality was broken

  • Corrected url in vqwiki.css for external URL image

  • Removed "--" for strike-through since it broke horizontal line ("----")

Improvement / Patch

  • Updated Italian translation

  • Changed RSS Servlet to produce RSS output that validates with feedvalidator.org (thanks Stuart)

Changes for version 2.7.9

Bug

  • RSS feed doesn't work for wiki accessed via HTTPS

  • Teach vqwiki that URLs can start with https as wel as http

  • Small error in ApplicationResources_nl.properties

  • Mail.smtp.auth=true property assignment required for (E)SMTP auth

Improvement / Patch

  • Support for strikethrough (--text--), superscript (^^text^^) and subscript (~~text~~)

Changes for version 2.7.8

Bug

  • 'mentioned on' behavior changes when attachments are indexed

  • Wrong special chars handling in RSSServlet

  • Wrong special chars handling in search box

  • Non localized messages in top navigation bar History page

  • vqwiki.PluginManager cannot find file

  • Lists break without spaces-to-tabs enabled

  • System claims lock is taken by someone else even when it is not

  • When I use [[UC 0002]] as an internal link it does not recognize it as a link

  • Search engine index setConnectionTimeout (instead of setTimeout) causes deadlock

  • set username accepts empty username

  • Notifications: not possible in Oracle

  • create_postgres.sql file missing in 2.7.7

  • Export2HTML seems to be failing us

  • Purge Deleted Topics not working with Oracle DB

  • Purge Deleted Topics not working when using MySQL

  • redirect: doesn't work with topic names surrounded by brackets ([[...]]) or backticks (`...`)

  • Problem with function Export2HTML

  • Diff.java license appears incompatible with LGPL

  • Search in ExportHTML doesn't work

  • Issue with generating membership confirmation email

  • VQWiki crashes on first use on WebSphere 5 (used to work)

  • Deleted topic remains on recent changes

Improvement / Patch

  • A new security contraint was added to the web.xml file. This will implement basic authentication for VQWiki It is turned off by default. To turn it on, uncomment the security-constraint section in web.xml and restart the application. Functionality: Shows a basic authentication pop-up so users can be authenticated against third party system. (with auth-ldap for example) If it is turned off, the normal cookie method will be used.

  • A new diff function was introduced. It uses stylesheet based layout, please also see the UPGRADE document.

  • It is now possible to redirect to topics with spaces. If the first word in the content is redirect, the rest will be used as the destination topic.

  • Passwords in the vqwiki.properties file can be encrypted now, see the admin screen.

  • Full support of Lucene Query Syntax

  • Adding prettylink in the form [http://www.vqwiki.org | the quicky wiki]

  • Add style class to tables produced by ####

  • Unsubscribe link in mail

  • Spanish translation

  • Passwords should be encrypted in property files

  • Add topic name to emailed "topic changed" alert

  • Add option to disable prepending numbers to attached file names

  • Patch to add possibility of basic authentication support instead of cookie

  • Lexer to implement MediaWiki Syntax

  • Change "Jump to" - "Search" Buttons to "Search" - "Jump to"

  • Clean up top menu

  • Fix (?) database connection handling

  • Standardize coding style

  • org.apache.log4j.Category is deprecated

Changes for version 2.7.7

  • Fixed bug in RSS feed where partial html codes in the description broke the feed

  • Fixed URL and i8n problem due to URL being encoded in UTF-8 and Tomcat trying to decode as ISO-8859-1

  • Fixed bug where a lock file is not deleted for topics with spaces (or other characters outside ASCII) in them

  • Added Norwegian translation

  • Added Polish translation

  • Added Swedish translation

  • Updated German translation

  • Updated Dutch translation

  • Added new documentation: the VQWiki Book, supplied in DocBook and HTML formats with the WAR file and downloadable as a PDF from the site. This new document replaces the old admin guide.

Changes for version 2.7.6

  • Improvements to the admin screen for quicker deployment.

  • Some fixes with regards to internationalization.

Changes for version 2.7.6

  • Improvements to the admin screen for quicker deployment.

  • Some fixes with regards to internationalization.

Changes for version 2.7.5

Bug

  • [ 1029961 ] - edit.js missing

  • [ 1205764 ] - Ordered list trouble

  • [ 814653 ] - admin-guide: wrong path for linking.properties

  • [ 1060306 ] - RSS plugin: Rss plugin's keep setting produces nullpointer?

  • [ 837452 ] - Export2HTML Problem - worked 1 time

  • [ 998848 ] - External link shows up in ToDo

Improvement / Patch

  • Addition of a basic preview option, including admin screen setting. Default behaviour is not to use it.

Changes for version 2.7.2

Improvement / Patch

  • Added support for spaces in display-name for link extender, e.g.: [c2:StartingPoints|C2 Starting Points] Will render the HTML:

    <a href="http://c2.com/cgi/wiki?StartingPoints>C2 Starting Points</a>

Changes for version 2.7.1

Bug

  • Fixed the plugin manager so that it does not require a context restart immediately after installing a plugin

  • Fixed Resin-specific bug where redirect from logout link was redirecting to root context instead of virtual wiki context

Improvement / Patch

  • Added support for actions to the plugin manager. Classes that implement vqwiki.WikiAction can be implemented and placed in plugin zips. The WikiAction.doAction() method supplies the servlet request and response so there is now no need to write new servlets and add mappings to web.xml to extend VQWiki functionality, they can be created as plugins rather than in the main code stream.

  • Altered menu so that it picks up the "StartingPoints" link from the default topic setting in the admin console. If you choose another default topic it will link to that instead of StartingPoints.

  • Added display-name behaviour to the link extender. A pipe after the section following the colon separates the display-name, e.g.: c2:StartingPoints|C2 Will render the HTML:

    <a href="http://c2.com/cgi/wiki?StartingPoints>C2</a>
  • Added Amazon default link extension that uses the ISBN number, e.g.: amazon:0201485672|Refactoring ...will produce a link with the text "Refactoring" to the Amazon book details for "Refactoring" by Martin Fowler

  • Added Internet Movie Database default link extension that uses the IMDB id number, e.g.: imdb:0246578|DonnieDarko ...will produce a link with the text "DonnieDarko" to the IMDB details for Donnie Darko :-)

Changes for version 2.7.0

Bug

  • Fixed problem where Tomcat 5 gave file not found errors if there was a space in the webapp install path

  • Fixed error in database mode about missing "FritzTextFormattingRules.txt"

  • Added missing return statement in SaveTopicServlet

  • Purging topics does not misreport the purging of pseudotopics (e.g. SetUsername)

Improvement / Patch

  • Field on menu that can be used to jump straight to a topic by name, or to search for the given text using the usual search engine.

  • Added "logout" link at bottom of topics to logout the current user. This is to enable virtual wiki switching when authentication realms have been added to separate virtual wikis. Link will only appear if there is an authenticated user principal is present.

  • "Minor edit" checkbox to optionally exclude changes from recent changes.

  • Added proper explanation for when less than two topics are selected in the arbitrary diff in history.

  • The "print this and how many pages below" form on the printable page version is hidden after being submitted.

Changes for version 2.6.4

Bug

  • Diffing of topics with spaces in the name

  • Fixed some resources with no space

  • Fixed encoding of topic names in menu item URLs

  • Changed breadcrumb trail to display the resource name of the virtual wiki correctly

  • Made read-only topic check case-insensitive

  • Fixed failure to unlock topics with special characters in the name

Improvement / Patch

  • Added proper back-link searching so that the "is mentioned on", OrphanedWikiTopics and ToDoWikiTopics are actually accurate, i.e. instead of an ordinary search being carried out, a lexer checks that the relationship is a proper link.

  • Added admin option to set whether to send more than one email change notification per topic per day.

  • Added admin console "panic" feature to delete all lock files and recent changes serializations in the event that locks are unable to be removed through the lock list.

Changes for version 2.6.3

Bug

  • Fixed bug with new "redirect:" pages

  • Fixed bug in option for separate title words on admin console

  • Added _en ResourceBundle to fix problem with Safari displaying incorrect locale

  • Fixed external linking breakage

Changes for version 2.6.2

Bug

  • fixed backtick wiki-name match so that a pseudo-shortest-match occurs

Improvement / Patch

  • Arbitrary diffing between versions on the history page.

  • Added admin setting to enable/disable indexing of attachments when search engine indexing runs. We have *very* large PDFs as attachments and the indexing process was taking several hours.

  • Admin option for making words in CamelCaps appear as separate words in the titles.

Changes for version 2.6.1

Bug

  • RecentChanges failures in file mode

  • OrphanedTopics failure

Changes for version 2.6.0

Bug

  • typos in default topics and "is mentioned on".

  • Code clean-up (some unused stuff)

  • Fixed \n added in bottom of each file read, that was adding a <br> in the bottom of each rendered page. (WikiBase.java)

  • fixed unclosed table tags in admin.jsp

Improvement / Patch

  • PostgreSQL added as a standard database type (thanks to Andre Gauthier for the info on the necessary script changes). Database type in admin console is now a combo box.

  • Added option "RecentChangesRefreshInterval" : When the user request the page "Recent Changes", it takes long time to generate it. As this page is often requested by users, because it briefly resumes all the updates on the web site, it charges a lot the server CPU load processing always the same information and producing the same page for different users. With this option you can customize the lifetime of the RecentChanges page, so different users requesting this page will get a "cached version" of the page until it expires. This greatly reduces server CPU load, speeding up the site.

  • DefaultLineBreaks is now by default set to 1.

  • CSS are now editable by remote as any other wiki page.

  • "Website-like" layout by Luigi. It's now possible to create a menu that will be displayed on the left side of each page, a "Top Area" (for the site logo and banner) and a "Bottom Area" (for sponsors etc.)

  • "AdminOnlyTopics" special wiki topic contains a white-space separated list of topics that only admin should be allowed to read or edit. By default this includes AdminOnlyTopics, TopArea, BottomArea and LeftMenu.

  • Back-porting of JFlex from VQWiki 3 Alpha to replace the ageing JLex based lexical analyser generation. This together with the addition of UTF-8 encoding by Martin Kuba for flat-file mode should clear up problems with non-Latin characters.

  • Admin option to set the encoding scheme - if you're already using ISO-8859-1 (the default prior to using UTF-8) you'll need to set the admin option to ISO-8859-1 or convert your existing files to UTF-8.

  • Czech translation by Martin Kuba.

Changes for version 2.5.5

Improvement / Patch

  • Italian translation by Jacopo Giudici.

  • Explicit wiki server hostname setting in admin console. This can be set to make the server sent out in email messages for the registration/notification system always appear as this server (useful if you use multiple URLs to access the same server).

  • Database connection pooling (Jakarta Commons pooling) and DataSource support added by Ernst Jan Plugge. See CONNECTIONPOOL_README and/or DATASOURCE_README in the Wiki installation directory for details.

  • Various stability improvements.

Changes for version 2.5.4

Bug

  • spaces in key escaped in pseudotopics.properties

Improvement / Patch

  • Proper Oracle support added by Ernst Jan Plugge. See the ORACLE_README in the Wiki installation directory under your webapps directory.

Changes for version 2.5.3

Bug

  • search indexing instability in file mode fixed

Improvement / Patch

  • Ability to set a target for external hyperlinks. This can be set in linking.properties, e.g. to make all links to pages outside the wiki open in a new window this can be added: hyperlinks.target=#blank

Changes for version 2.5.2

Bug

  • purge deleted in database mode fixed (didn't work with some MySQL drivers)

  • tag error when adding new members fixed

  • fixes for Lucene search indexing

  • bugs with cancel/save under German locale fixed

Improvement / Patch

  • Tobias added new pseudotopic WikiStatistics that gives a breakdown of Wiki usage stats.

Changes for version 2.5.1

Bug

  • append template failure fixed

  • admin console now adds and removes read-only topics for the current virtual wiki

  • text area in history is read-only

Changes for version 2.5.0

Bug

  • orphaned topics now working again

  • whitespace problem in search results resolved

Changes for version 2.5.0 RC 2

Bug

  • nested tag upsetting Resin removed

  • admin console login/logout failed redirection on Resin fixed

  • history was still wrong, fixed properly this time

  • table text font same as body text font

  • Upgraded standard taglib to version 1.0.3, getting rid of the last edit date bug in the process.

  • Font size in pre/code/tables same size as body (except it doesn't seem to be on Mozilla - does anyone know why fixed width font on Mozilla shows up smaller than sans serif?)

Changes for version 2.5.0 RC 1

Bug

  • reserved word "user" changed to "wikiuser" for ANSI compliant database mode

  • history was returning incorrect versions from main list and next/previous were the wrong way around

  • clicking admin link defaults to admin username on login page

  • breadcrumb trail respects virtual wiki boundaries (the trail gets reset on boundary)

  • printable pages with depth > 0 do not include pseudo-topics (e.g. RecentChanges)

  • Changed the heading lex behaviour to ^!.+[^\n]! ^!!.+[^\n]!! etc.

Improvement / Patch

  • I registered the domain name veryquick.org, so all the email addresses etc have been changed to reflect this. The old domain is still active though, so don't worry about updating existing links.

  • Virtual wiki list: clicking on the "Wiki" part of the page header (the bit before the virtual wiki name) will show a list of virtual wikis that are available. This can be suppressed in the admin console if you don't wish all users to see all virtual wikis. The virtual wikis can now have friendly names set in WEB-INF/classes/ApplicationResources.properties. (Should the friendly name go in the page header??)

  • Some further German translation by Tobias.

Changes for version 2.5.0 BETA 3

Bug

  • fixed the RecentChanges problem where multiple virtual wikis were being displayed on the default virtual wiki's recent changes.

  • Various other stability issues.

Improvement / Patch

  • Changed the heading lex behaviour to !.+[^\n]! !!.+[^\n]!! etc.

Changes for version 2.5.0 BETA 2

Improvement / Patch

  • Tobias Schulz-Hess implemented Lucene as the search engine - full query syntax, search term highlighting etc!! He has also added a breadcrumb trail.

  • Tobias also created an RSS feed: e.g. http://localhost:8080/wiki/jsp/Wiki?RSS

  • For developers: reorganized package structure thanks to J Carlsson's suggestion.

  • For users: the lexers now have the logical names vqwiki.lex.LinkLex etc when setting them in the admin console. This means they will need setting on an upgrade, if you use your old properties file so set add the .lex bit to each of the lexers names (see UPGRADE for more lucid instructions).

  • Placing a file called "wikiname.ignore" in WEB-INF/classes that contains a list of WikiNames (one per line) will mean that those names are not treated as WikiNames by the lexer (they won't be linked).

  • Java2HTML upgrade - thankyou Markus Gebhard.

Changes for version 2.5.0 BETA 1

Bug

  • Correct input and display of high unicode characters, e.g. Japanese, Chinese etc.

Improvement / Patch

  • Improved performance of RecentChanges in file mode.

  • "ANSI-fied" the SQL used to create tables and to search the database. This means that VQWiki should now work with most databases. Added an admin console option for "database type". This defaults to "mysql", but can be set to "ansi" to use the ANSI SQL.

  • Topic redirection. To make one topic automatically redirect to another, simply make the contents of the topic "redirect:TopicName". Of course, this makes it rather difficult to undo a redirection, since any attempt to get to the topic will result in a redirection to "TopicName". So, there is a forced edit format: "edit:TopicName" will link directly to the edit of "TopicName".

  • Internal security management. The web appliaction security context is no longer used for admin console authentication. The first time you run (or upgrade to 2.5.0) VQWiki you will be shown a password on the first topic you access. This is the admin password. The admin username is "admin".

  • Added new link-lexer "LinkLexLoose" that allows WikiNames to be constructed from words with more than one consecutive uppercase letter, e.g. WiKIName. LinkLexLoose is not the default link-lexer, but it can be set from the admin console.

  • Admin password change on the admin console.

  • Default topic setting on admin console - the topic set here will be the one that greets users if they go to the base of the wiki context (index.jsp).

  • Topic total on all, orphaned and todo topics pages.

  • Lock list console with unlocking (requires admin login).

  • Extensible "pseudo-topic" makes adding new special topic URLs easier when writing plugins.

  • Templates are now appended to the topic while it is being edited, rather than appending on the topic save.

  • Commencement of the internationalization of strings, titles, captions etc.

  • Confirming membership by email doesn't require the username cookie to be on a machine already. If the cookie isn't there at confirmation time, it will be resent.

Changes for version 2.4.0

Bug

  • Bug with env-entry explicit properties file setting fixed.

  • Fix for bug with re-requesting membership confirmation in database mode.

Improvement / Patch

  • Added \__ to allow entry of double underscores (__ are normally the special character for no formatting).

  • Three-spaces are not converted to tabs when inside a preformatted section.

  • History in date descending order in file mode.

Changes for version 2.4.0 RC 3

Bug

  • Fixed the way that the confirmation URL is produced when subscribing to email notifications. The confirmation URL is now always based on the URL the user subscribed from.

Improvement / Patch

  • Re-introduced the "convert spaces to tabs" option on the edit page. Added admin setting to set the default for this.

Changes for version 2.4.0 RC 2

Bug

  • fixed web.xml bad reference to /AdminServlet

Changes for version 2.4.0 RC 1

Bug

  • Further fixes for international wiki names.

  • Infinite looping during searching for plugins when no user directory found fixed.

  • Removed dangling reference in CSS to background image.

Improvement / Patch

  • If "force setting of username" is on, when the user is forced to set their name on an attempted edit, they are redirected back to the edit after setting it, rather than just left at the "thankyou" page.

  • Images uploaded as attachments now appear inline in topics.

Changes for version 2.4.0 BETA 2

Bug

  • Fixed database mode locking behaviour, backing out editing a topic and re-entering without using cancel now keeps the lock rather than acting as though the user has lost the lock.

Improvement / Patch

  • Version browser - click the "history" menu item on any topic to see a list of the versions of that topic. Clicking a date in the list produces a display of both the marked up version and the original contents. The original contents can then be used to restore damaged topics.

  • The history view has "next", "previous" and "current" menu options so it is possible to scroll through each version of a topic.

  • Absolute URLs can be used for the customized logo.

Changes for version 2.4.0 BETA 1

Bug

  • Truls Thirud's fixes to allow internationalized WikiNames.

Improvement / Patch

  • New look'n'feel, courtesy of Joachim Lous. This includes the display/link-to of the current virtual wiki in the header (if more than one virtual wiki exists)

  • Extensible lexer system including Java source code formatting as an example. Surround some Java code in [<java>] [</java>] to see the effects.

  • Extensible lexer also provides full HTML include: surround HTML in [<html>] [</html>] and VQWiki will ignore the markup and output HTML exactly as entered.

  • Much of the scriptlet code in the JSPs has been replaced with common taglib tags and custom VQWiki tags. This makes the JSPs a lot easier to debug and enhance.

Changes for version 2.3.6

Bug

  • Occasional bug with security error on emailing fixed.

  • The last character of the last cell in a table is not truncated.

Improvement / Patch

  • Orion-specific fixes that enable correct operation of mail notification system and printable page feature.

  • Combo-box to select the virtual wiki that you wish to purge deletes from.

  • OrphanedTopics are alphabetised.

Changes for version 2.3.5

Bug

  • Fixed SMTP authentication settings that weren't saving from the admin console.

Improvement / Patch

  • Added attachment-type setting. Attachments can be delivered inline or as "attachments". Inline means they get opened by the browser (in a new window). "Attachment" means they become prompt for a download straight away.

  • The admin console reports which files were deleted on a purge.

Changes for version 2.3.4

Bug

  • Fixed content header delivery so the correct filename and type for the attachment is sent on viewing.

  • Fixed IE-specific (it was working under Mozilla) file upload problem with full path names being appended to to upload directory instead of just the filename.

  • Fixed problem with read-only topics not being deleted from the admin console when in file mode.

  • Fixed SMTP authentication settings that weren't saving from the admin console.

Improvement / Patch

  • Added the file upload size limit setting to the admin console.

  • Included activation.jar (email notification dependency) and commons-logging.jar (file upload dependency) in the lib directory.

Changes for version 2.3.3

Improvement / Patch

  • More rigorous save checking to avoid poorly written web crawlers saving blank topics.

Changes for version 2.3.2

Bug

  • Numbered lists were not working, they are now.

Improvement / Patch

  • A new line is appended if there is none on topic reads. This stops problems with unterminated tables and lists.

  • A code tag in the same style as the FritzLex has been added to the default lexers: e.g. {{{here is some code}}}

  • An admin option to turn off templates has been added (in case you wish to conserve screen real estate)

  • Updated quick edit help.

Changes for version 2.3.1

Bug

  • Fixed bugs in admin page - some settings not saving.

Improvement / Patch

  • Switched to 3 pass parser: one for layout, one for format and one for linking. The 2 pass can not put bold, italic etc in tables and lists.

Changes for version 2.3

Improvement / Patch

  • Printable page link in topic menus brings up a page with just the header and contents.

  • The number of line breaks to insert in the HTML on a new line in the text can be set from the admin console. This means you can squeeze everything up a bit by setting it to "1" rather than "2" (which is what VQWiki has been using until now - the default is 2).

  • Extensible links. "links.properties" now holds expansions for prefix:url format links. This makes it easy to add extra linking to other Wikis or internal web systems like WebCVS.

  • Sublists. Use multiple groups of three spaces to create lists within lists.

  • Improved attachment system. Special syntax for absolute path for uploads is not required. Content is delivered directly by servlet rather than having to place the attachment in a location relative to the JSP context. "mime.types" can be used to specify by-extension content types. SmartUpload is no longer used - now using Jakarta Commons upload.

  • Improved text formatter. The lexing is now performed in two passes, this has meant fixes are possible (and have been implemented) for strange list and table behaviour. A unit test for the lexer has also been added to help with further lex enhancements.

  • SMTP username and password added to admin console for users who require authentication on their SMTP servers.

  • Templates are now available in file mode as well as database mode.

Changes for version 2.2.1

Bug

  • Minor bug fix for issue with Apache/Tomcat delivering content to Mozilla/Netscape browsers. A content-type header is now added explicitly, previously the HTML source would be displayed instead of being interpreted when viewing pages from Apache/Tomcat with Mozilla-based browsers.

Changes for version 2.2

Bug

  • Fixed "Last Edited" date in file mode.

  • Fixed problem with list not working if started on the first line.

Improvement / Patch

  • Email notification of topic changes is now implemented in file-mode and database-mode (the groundwork for this was all done by Robert Brewer).

  • Maximum number of backlinks can be set (default = 20).

  • In file-mode, RecentChanges are now serialized via JSX to XML, so there will no longer be a problem with upgrades making the binary file incompatible between versions. It will be simple to write a script to update the file to any new change version.

Changes for version 2.1

Improvement / Patch

  • Clicking on a topic title searches for occurences of that title.

  • "Edit page" and "Attach" links no longer appear when a topic is marked read-only.

  • Added "quick help" to edit page.

  • Added "virtual wikis", more than one Wiki can now be run from the single server instance. All it requires is adding the name in the admin console and a single servlet mapping to the web.xml file. See VIRTUALWIKI_README for details.

  • Added orphaned-topics search and all topics listing: "AllWikiTopics" and "OrphanedWikiTopics" respectively.

  • Fixed database-mode search so that it searches on topic name as well as contents.

  • Added WikiServlet so all topic requests are directed at "Wiki". Redirection occurs back to "Wiki" rather than forwarding, so the page can be refreshed after saving without causing re-saving to occur. Dynamic topic requests are now intercepted by the servlet rather than by the topic.jsp.

  • The logo now features a French Orca by the name of "Wiki". :o)

  • The Database support now uses a MySQL regular expression to do the searching, consequentially it database support will no longer (sort of) work with MS SQLServer or other non MySQL syntax platforms.

  • Format-ignore character is now two underscores rather than one so the underscore can be used normally.

  • Localised date formatting on "last edited" menu item.

  • Tables markup using #### and ##.

  • Pre-formatted text markup using @@@@.

  • Menu at top and bottom of the page.

  • Added supported for a deployer-defined logo image.

Changes for version 2.0 BETA 2

Bug

  • Noel fixed database connections so a connection dropped by the database is reconnected.

Improvement / Patch

  • Change from GPL to LGPL for licence on advice of many people. Particularly because of the inclusion of non-GPL library code in VQWiki (log4j).

  • Added read-only topic support to database layer (previously only for flat-file mode).

  • Improved default topic creation, default topics are now stored as text files in the class path rather than being hard-coded.

  • Improved error handling.

  • Added new enhanced text-formatter mode created by Fritz Freiheit. The new mode can be toggled from the admin console. A new default topic called FritzTextFormattingRules explains how to use the enhancements.

  • Added entry for index.jsp to web.xml.

  • Made initial config more robust so it is possible to reconfigure from admin console if in database mode and database connection fails.

Changes for version 2.0 BETA 1

Improvement / Patch

  • MySQL database back-end support. The native file-system operates by default after installation, but database support can be setup and started from the admin console. See MYSQL_README.

  • Added new escape sequence __ that ignores any formatting inbetween.

  • Made TextFormattingRules a normal Wiki topic.

Changes for version 1.8.2

Improvement / Patch

  • Moved the properties file to the classpath, using the Log4j Loader to locate it. This will avoid problems with running the web container as an anonymous user with no home directory and limited access to the Tomcat directory. It can found in WEB-INF\classes.

  • Made the Wiki file-system (home) directory changeable from the admin console. This can be changed on the fly, but it takes a few seconds for the web container's class loader to detect that the properties file has been modified and reload the handler... so an exception will occur if the home directory is changed while running and then a page is accessed too soon.

  • Added an "allow back-tick" setting to the admin console. This means that the back-tick automagic WikiNames e.g. `ACM` can be disabled if required. Back-ticks are not a standard Wiki convention.

Changes for version 1.8.1

Bug

  • Fixed lexer so that numbered lists appear correctly when preceded by a blank line.

Improvement / Patch

  • Shawn created new locking mechanism where an error message is generated if the lock that a user editing a document times out. Now they can not overwrite the changes made by the person who acquired the timed-out lock.

  • Automagic links to c2.com and Meatball wikis. E.g. c2:StartingPoints, mb:RecentChanges

  • The topic names themselves are now indexed in the search engine.

  • RecentChanges ordering is now most recent to least recent.

Changes for version 1.8.0

Bug

  • Fixed search engine index rebuild to refresh table completely (ooops).

Improvement / Patch

  • Bill added switchable support for HTML, toggled from admin console.

  • Added https as a protocol that automagically turns into a link.

  • Switched to using proper lexical analyser for tokenizing into the search index so HTML tags are stripped and punctuation removed.

  • Changed JSP comments so that they are not output to the browser.

  • Added support for binary file uploads that produce an inline link of the form attach:filename.ext. This allows the attachment of files to topics.

  • Added versioning cache to speed up finding where the previous revision is.

  • Added log4j as the logging engine (http://jakarta.apache.org/log4j).

  • Put all properties in a single properties file in the working directory.

  • Added security constraints to web.xml to allow administrators to setup up security for allowing edit access to only some users. The constraints are commented out by default.

Changes for version 1.7.0

Improvement / Patch

  • Custom wiki directory can be set by placing a properties file called "vqwiki.properties" in the working directory for the web container and setting a property "dir" to a directory name (the directory will be created by vqwiki on startup).

  • Topics can be made read-only from the admin console.

Changes for version 1.6.3

Improvement / Patch

  • Work-around for Tomcat 2.x and 3.x to prevent exception when saving. This problem should be fixed in the next released versions of Tomcat.

Changes for version 1.6.2

Bug

  • Fixed text-formatter to handle Unicode so non-English alphabet characters can be used.

Changes for version 1.6.1

Bug

  • Fix for problem with backtick sequence only allowing one match per line.

  • Fix for terms with digits not being search-indexed correctly.

Changes for version 1.6

Improvement / Patch

  • Diff capability.

  • Username cookies.

Changes for version 1.5

Improvement / Patch

  • Improved UI.

Changes for version 1.4

Improvement / Patch

  • Admin console.

  • Search engine.

Contributors

Project Lead

Marcello Teodori

Developers Marcello Teodori, Bruno Bossola, Filippo Diotalevi, Gian Carlo Pace, Martijn van der Kleijn, Andreas Studer, Colin Jacobs, Tobias Schulz-Hess, Fritz Freiheit, Gareth Cronin
DocumentationTim Howland
Translation Maintainers 
CzechSasha Kotlo
DutchMartijn van der Kleijn
EnglishMarcello Teodori
French<position vacant>
GermanNico Jabin
ItalianMarcello Teodori
NorwegianErik
PolishMichael (mindweb)
SpanishZapo (erzapo)
SwedishJohan Lindell
Non-project Contributors:Fabrizio Zellini, Fritz Kunstler

License

VQWiki is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version. This software is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details. You should have received a copy of the GNU Lesser General Public License along with this software; if not, write to the Free Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. Appendix B of this document contains a copy of this license.

This documentation is released under the GNU Free Documentation License. Please see Appendix A for details on this license.

About This Documentation

Document Structure

This document is intended to assist with all phases of installing, maintaining, and contributing to a site based on the VQWiki software. The documentation is divided into four major chapters:

  • Chapter 1: About VQWiki - describes the project, this documentation, and the resources that are available to administrators and users.

  • Chapter 2: Administrator's Guide - Covers how to install, configure, and maintain a VQWiki installation

  • Chapter 3: User's Guide - Guide to Wikis in general, and specific features of VQWiki

Getting the latest version of this document

This document will be available from the VQWiki website at http://www.vqwiki.org.

Where to go for help

Mailing Lists

There are two lists available to support VQWiki users.

The Announcements list is a moderated low-volume list for new version announcements and bug fixes. Signup information and list archives are available at: http://lists.sourceforge.net/lists/listinfo/veryquickwiki-announce

The VQWiki User's list is for support, questions, and discussion of proposed new features. Signup information and list archives are available at: http://lists.sourceforge.net/lists/listinfo/veryquickwiki-users

VQWiki Site

The VQWiki site is located at http://www.vqwiki.org. Resources there include a Wiki containing updated support information contributed from all users, the latest version of this document, additional plugins, issue tracking, and other items.

Chapter 2. Administrator's Guide

Wiki Functions

This section will touch on the major mechanisms available in VQWiki. The more complex mechanisms receive their own sections later on.

Editing

Any topic in a Wiki may be edited. The user clicks the "EditPage" link at the top or bottom of the page, makes changes, clicks the "Save" button and is redirected back to the page of the topic page that the user has edited.

WikiNames

A WikiName consists of two or more words with initial capitals, run together. A WikiName appears as a word in "CamelCaps". The syntax of a WikiName is a

Uppercase letter

Lowercase letter(s)

Uppercase letter

Lowercase letter(s)

Examples of well-formed Wikinames are: WikiWord or GoodStyle. When you type a WikiName, you establish a hyperlink. It's as easy as that. VQWiki also allows topic-naming by surrounding a word or phrase in back-ticks, such as `Gareth Cronin`.

Linking

When you edit a page by typing a WikiName, the WikiName will appear with a question mark (?) link appended to the end of the WikiName. Click the question mark. You will then be directed to the edit function mode of the page that will be identified by the WikiName you created. Save the page. Now your WikiName will be displayed as a link to the new page any time the WikiName appears in the Wiki, thus making your WikiName a hyperlink. It's as easy as that.

Searching

Each page contains a text field for searching. The search button performs a full-text search based on the text in the text field and returns 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

By using the SetUsername reserved topic, a user can set a username for herself/himself. This function sends a cookie to the browser to identify the user in the future. Usernames are displayed in RecentChanges and are necessary for email notification. Wiki 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).

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.

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 one of the other shipped lexers) and StartingPoints (a default start page).

Installation

Supported Systems

The VQWiki software runs on top of so-called application servers. These are pieces of middleware software that provide a set of functionality to hosted applications. The following software requirements are necessary for VQWiki:

  • A servlet container that supports Java Servlet 2.3 and JSP 1.2 specifications.

  • Any stable web browser such as Internet Explorer 5.x, Netscape 7.1, Mozilla 1.4 or Opera 7.11.

  • Java SDK 1.4 or higher depending on the requirements of your servlet container.

  • By default, VQWiki runs with flat-file persistence. But an easy to configure database connectivity option is available.

VQWiki is tested with Apache Tomcat 5.5.27 and JDK 1.4.2 [3]

Known Configurations

Users have also reported successful implementation with the following servlet containers:

  • Apache Tomcat 5.5.x e 6.0.x

  • JBoss 4.x

  • Orion 1.6

  • Resin 2.1.9

  • Allaire JRun 4.x

  • BEA Weblogic 7.x

  • IBM Websphere Application Server 5.1.x

  • IBM Websphere Application Server 6.x

  • Oracle 9i Application Server

Note: Tomcat 3.x or earlier is not recommended for use with VQWiki.

Quick start

The installation process is essentially the same as any other web application. The quickstart guide here assumes you will be working in a development or testing environment. For production systems, please consult the Basic Installation and Database-backed persistence sections, below.

  • Shut down your application server

  • Copy the WAR file to your web applications folder (on Tomcat, this will be {TOMCAT_HOME}/webapps)

  • Restart your application server

  • Browse to your application server and access the VQWiki URL: eg. http://localhost:8080/vqwiki-2.8.1

  • As this is a first time installation, click on "StartingPoints" to retrieve the randomly generated administrator's password

The system should now be running correctly, with flat-file persistence. See the troubleshooting section (below) for assistance with common problems.

IMPORTANT: Before deploying VQWiki to your production environment, be sure you review and understand the section below on Security Issues and Workarounds.

Basic Installation

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.

The following assumes you have installed Tomcat on a Windows machine at {TOMCAT_HOME} 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.8.1.war. The name of the WAR file may be different in which case you should substitute your WAR file name for vqwiki-2.8.1.war. Finally, we will assume you have a Web browser available on the installation machine.

To install VQWiki, you should follow your application server instructions for deploying a WAR. Usually it's just a matter of moving the WAR file into the webapps directory. You may need to restart your application server if it does not recognize the new war file and install it. Once the file is installed, browse to http://localhost:8080/vqwiki-2.8.1, and that's it!

For the tomcat 4.X series, the process is:

  • Shut down your application server

  • Copy the WAR file to your web applications folder (on Tomcat, this will be {TOMCAT_HOME}/webapps)

  • Restart your application server

  • Browse to your application server and access the VQWiki URL: eg. http://localhost:8080/vqwiki-2.8.1

Now that VQWiki is installed, you should perform some basic configuration work. In order to do this, you'll need to retrieve the administrator's password from the system. On the opening screen, you'll see a list of links - the first one listed is StartingPoints. Choose StartingPoints to be directed to a special page where you will receive a password to access the administrative functions. Memorize this password!. If you miss the password, or you forget it, see the section on password recovery.

By default, VQWiki runs with flat-file persistence and other default options. Choose the "Admin" link at the bottom of any topic to access the administrative functions where you can customise VQWiki. The administrator username is "admin". In the chapters below we address setting up database persistence and other VQWiki options.

IMPORTANT: Before deploying VQWiki to your production environment, be sure you review and understand the section below on Security Issues and Workarounds.

Upgrading

There are numerous combinations of old and new versions that it is possible to upgrade between. Here we try to cover the more typical scenarios.

Always make a backup of your wiki home or your wiki database (which ever you are using) before attempting any upgrades!

When upgrading, it is best to first try out the new version in its own context but pointing at your existing wiki home or wiki database. That way you can keep using the old version until you're happy that the new version is doing its job.

Upgrading from 2.8 to 2.8.1

Just backup you wiki directory and the vqwiki.properties file. For any file you might have modified or added in the expanded webapp content, also backup them, then start with the new WAR file and review them before copying them over.

Upgrading from 2.7.9 to 2.8

The MySQL JDBC driver is not included anymore in the distribution, you have to manually download it and install it within the VQWiki application or on your server. See the database persistence section for details

Upgrading from 2.7.7 to 2.7.9

The default StyleSheet contents changed. As such, it is necessary to update already existing StyleSheet topics with the following class:

.menuinactive {
  font-family: Trebuchet MS, Verdana, Helvetica, sans-serif;
  font-weight: bold;
  text-decoration: none;
  color: #aaaaaa;
}

If this is not be done, inactive menus might be the cause of "jumps" in the menu structure. There are also the following new CSS styles: How to display new topics, for example in red:

a.newtopic {
  color: #FF0000;
}

How to display external links, for example with an icon:

a.externallink:after {
  content:url("../images/external.png");
}

How to display tables generated by the wiki:

table.wikitable {
  color: red;
}

How to display author details:

.authordetails {
  width: 350px;
  border: 1px solid #8E9EAD;
  padding: 3px;
  float: right;
  margin-right: 4%;
}

The following stylesheet entries were added to accomodate the new diff code:

/* diff page */

table.diff {
  border: 0;
  margin: 0;
  padding: 0;
  width: 100%;
}
td.diff-delete {
  background: #ee7777;
  font-weight: bold;
  padding: 0.1em;
  width: 49%;
}
td.diff-add {
  background: #77ee77;
  font-weight: bold;
  padding: 0.1em;
  width: 49%;
}
td.diff-unchanged {
  background: #dddddd;
  padding: 0.1em;
  width: 49%;
}
td.diff-indicator {
  font-weight: bold;
  padding: 0.1em;
  text-align: right;
  width: 1%;
}
td.diff-no-indicator {
  padding: 0.1em;
  width: 1%;
}
td.diff-line {
  padding: 0.5em 0.1em 0.1em 0.1em;
  font-weight: bold;
}

Upgrading from 2.7 to 2.7.7

If you had problems with lock files not being deleted, you can delete those manually if necessary. The layout of the RSS feed changed slightly, the font's color was removed for example, so you might want to update any applications listening to the feed.

Upgrading from 2.6 to 2.7

Search index changes sometimes render the temporary search index files useless. Delete these from your web container's temporary directories to reset the search index. E.g. on Tomcat delete your {TOMCAT_HOME}/work/{mode}/{host}/{wikicontext} directory.

Upgrading from 2.5 to 2.6

There is a now a "website-like" layout. This consist of a TopArea, BottomArea and LeftMenu. Each of these is held as a wiki topic. So just edit the topics as given to change the content of the basic layout. The three topics are now locked down as admin-only topics. A list of topic names lives in a topic called AdminOnlyTopics. Removing topic names from this list will open them up to anyone.

Upgrading from 2.4 to 2.5

The package structure has changed, lexers are now in their own package called vqwiki.lex. This means that if you are using the same properties file for 2.5 as for earlier versions, you will need to go into the admin console and make the following changes:

  1. LinkLexer: vqwiki.LinkLex becomes vqwiki.lex.LinkLex

  2. FormatLexer: vqwiki.FormatLex becomes vqwiki.lex.FormatLex

  3. LayoutLexer: vqwiki.LayoutLex becomes vqwiki.lex.LayoutLex

Upgrading from 2.2 to 2.4

File uploads are now stored and retrieved directly by a servlet, so they don't have to be in a directory relative to the JSPs. You will probably need to change your setting for the upload directory to an absolute path (but with no '@' in front of it). The default virtual wiki "jsp" uploads are now stored in a directory under the upload directory called "jsp". This will be created on the first upload, but you will need to shift any existing files in the root of your upload directory into the "jsp" folder.

The other major change is the way that the lexer (the thing that does the formatting from the Wiki markup and the automagic linking) operates. The lexer is now loaded dynamically to make it easier for people to create their own lexers. Previously you could select either "Standard" or "Fritz" from the admin console. Now if you wish to run the standard (it will default to this anyway) the settings are:

  1. Format Lexer: vqwiki.lex.FormatLex

  2. Link Lexer: vqwiki.lex.LinkLex

If you are using the Fritz lexer, then you need to change this to:

  1. Format Lexer: vqwiki.lex.FritzLex

  2. Link Lexer: nullx

The Fritz lexer only makes one pass, so the second pass is unnecessary.

Upgrading from 2.0 to 2.2

If you're using database persistence, as some additional fields were added to 2.2 to facilitate "virtual wikis", you'll need to run the following script on your MySQL database (don't forget to backup your database first):

ALTER TABLE Topic ADD COLUMN virtualwiki VARCHAR(100);
ALTER TABLE TopicVersion ADD COLUMN virtualwiki VARCHAR(100);
ALTER TABLE TopicChange ADD COLUMN virtualwiki VARCHAR(100);
ALTER TABLE TopicLock ADD COLUMN virtualwiki VARCHAR(100);
ALTER TABLE TopicReadOnly ADD COLUMN virtualwiki VARCHAR(100);
ALTER TABLE Topic DROP PRIMARY KEY;
ALTER TABLE Topic MODIFY virtualwiki varchar(100) NOT NULL;
ALTER TABLE Topic ADD PRIMARY KEY(name,virtualwiki);
UPDATE Topic SET virtualwiki = 'jsp' WHERE virtualwiki = NULL;
UPDATE Topic SET virtualwiki = 'jsp' WHERE virtualwiki = '';
        

Persistence - The Default File-System

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 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.

Migrating to database-backed persistence

Overview

VQWiki is configured to use flat-file persistence by default. This means that it stores all wiki pages and assets directly on the filesystem. This is fine for smaller implementations, but there are performance issues around searching, indexing, and cross-linking new topics. VQWiki can be easily configured to use database persistence, which leads to much better performance for larger wikis. These directions are oriented toward MySQL which is the default database choice; see below for Oracle-specific notes.

General Steps

To use database persistence, you must have the the JDBC driver for your database installed in the classpath of your web container, or in the WEB-INF/lib directory of the VQWiki webapp. For MySQL you can download the latest version of the MySQL JDBC driver from: http://www.mysql.com/products/connector/j/index.html.

You should then start by creating a database instance for vqwiki, as well as provisioning a username and password for the system to use.

If you are using MySQL, these steps would look something like:

  • create database vqwiki;

  • grant all on vqwiki.* to vqwiki@localhost identified by 'vqwiki';

  • flush privileges;

This will create a database called vqwiki on the database machine, and will allow a user named 'vqwiki' full access to the system. 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: grant all on vqwiki.* to vqwiki@your-vqwiki-server identified by 'vqwiki';

It's probably a good idea to change this password to something that is more difficult to guess, particularly if this is to be used in a production system, or if the wiki may contain sensitive information. The root MySQL user and password should not be used for security reasons.

VQWiki will generate its own tables and copy data into them, so once the database configuration is done, the remaining work can be performed within the VQWiki Admin console. Click on the "Admin" link on the bottom of the page, and enter your administrator's password to view this page.

In order to switch to database persistence mode, you will need to change the following settings:

  • Persistence - change this from "Flat-File" to "Database". This will activate the additional fields you will need to configure.

  • JDBC Driver Class - by default, this is the MySQL driver (com.mysql.jdbc.Driver). If you need to use a different driver, enter it here.

  • Database type - select either mysql, ansi, postgres, or oracle.

  • Database URL or JNDI Datasource name - This is dependent on your setup. By default, the URL is set to jdbc:mysql://127.0.0.1/vqwiki , which translates to "The database named vqwiki, installed on the mysql database that's running on the host with IP address 127.0.0.1". You may need to edit this URL to connect to a different host, or to use a different JDBC driver. You can also use this area to specify that your database configuration is managed by JNDI- see below.

  • Database Username - this is the username for database access, as set above.

  • Database Password - this is the password for database access, as set above.

Once the database persistence is set, select "Save Changes". This will connect to the database, create the tables, and verify that everything is working. If you see database connection errors, there are several items to try:

  • Make sure that you are allowed to connect from the host that is running VQWiki to the host that is running the database. Most database systems are designed to be very restrictive about what hosts are allowed to connect with them. If you are using MySQL, try running it from the command line on the VQWiki host, as in: mysql -u vqwiki -h localhost -p vqwiki . If you cannot connect, then there may be a firewall or other issue that needs to be resolved before you can continue.

  • Check you have put your database JDBC drivers into a location that VQWiki can access. For a development system, it may be simpler to download the JDBC drivers that are designed for your database, and copy them to {installdir}/vqwiki-2.8.1/WEB-INF/lib . You should also obtain the JDBC driver name and URL format from the documentation at the developer's website.

Once that the database is successfully tested, scroll to the bottom of the Admin console, and look for an entry that says "Import from File to Database". This will copy your Wiki topics from the local filesystem to the database system you created. Note that attachments and plugins will remain on your filesystem, and will not be copied into the database. Any backup system you deploy must backup the local files as well as the database files to avoid problems.

Please see the section on Connection Pool tuning to maximize your database performance.

Configuring JNDI Data Sources

VQWiki can use a J2EE style DataSource retrieved through JNDI as a source of database connections. The procedure is as follows:

Configure a JDBC DataSource in your container and make it available through JNDI. Consult your container's documentation for details. Note the JNDI name needed to look it up. VQWiki will look up the name from an InitialContext instance, so you'll probably have to prefix your JNDI name with "java:comp/env/". For example: "java:comp/env/jdbc/VQWikiDb".

In the administration console, configure VQWiki for database persistence as above, but with the following changes:

  • The driver class name field can be left empty.

  • All connection pool settings are ignored.

  • Either configure a username and password in your DataSource, or specify a username/password pair in the admin servlet, but not both. I've only tried the former, but the latter should work if your DataSource and JDBC driver support it. Leave the username and password fields empty if your DataSource has the login credentials.

  • Set the Database URL to the JNDI name. VQWiki distinguishes between the two by looking at the URL. If it starts with "jdbc:", it's assumed to be a JDBC URL, otherwise, it is assumed to be a JNDI name.

That's it. If you only want to use a DataSource to realize connection pooling/testing/recycling, consider using the builtin connection pooling support instead. See "Connection Pool Tuning" below for more details.

Connection Pool Tuning

VQWiki's Database persistence mode uses the Apache Commons DBCP (Database Connection Pooling) to provide robust database performance.

Nothing special needs to be configured to make this work, it's there out of the box. The default configuration should suffice for most situations, but all connection pool parameters are configurable from the administration page.

These options should be self-explanatory. For more details on the inner workings of DBCP, take a look at the DBCP and Pool homepages:

If you want to use a database type other than MySQL, you should pay close attention to the "validation query" parameter. This is a small query to be executed to test the validity of the connection. For MySQL, the query "SELECT 1" is appropriate, which is the default. No table is specified, because the fact that the query is received and processed by the server is enough to ensure the connection is still alive and well. For other database types, other queries are appropriate. For Oracle, "SELECT COUNT(*) FROM DUAL" is a useful validation query. The table "DUAL" is a special built-in table with a single row for exactly this kind of purpose.

If you use another database type, consult your database's documentation for details on what is a usable validation query for you.

Oracle Notes

In order to use Oracle as your persistence layer, you will need the classes12.zip Oracle JDBC Thin driver. Either include it in the WEB-INF/lib directory of the VQWiki webapp, or in a container-specific lib directory that is made available to your container's webapps. For Tomcat, that is {TOMCAT_HOME}/common/lib. In the case of Tomcat, rename the file to classes12.jar. The Tomcat classpath builder doesn't see zip files as libraries.

This code should also work with the OCI driver. However, you're on your own as to configuring the native code library so that the OCI JDBC driver can see it.

The classes12.zip can be downloaded from: http://www.oracle.com/technology/software/tech/java/sqlj_jdbc/index.html

In the VQWiki Administration Console, specify the following:

  • JDBC driver class: oracle.jdbc.driver.OracleDriver

  • Database type: oracle

  • Database URL: jdbc:oracle:thin:@dbserver:port:dbname

  • Database Username: as appropriate

  • Database Password: as appropriate

  • Validation query: SELECT COUNT(*) FROM DUAL

Fill in the values for dbserver, port and dbname in as appropriate for your environment. Ask your database administrator.

VQWiki will automatically create the tables if it has the privileges to do so. If not, ask your database administrator to execute the create_oracle.sql script as the schema owner. This script is located in {installdir}/WEB-INF/classes.

VQWiki will try to recreate the tables every time it starts up. This will cause errors such as: java.sql.SQLException: ORA-00955: name is already used by an existing object. These can be safely ignored.

If you get "Table or view does not exist", even though the tables do exist, there is a database configuration problem. The database user must be able to see the tables without prefixing a schema name. You may need to create public synonyms for the tables if the schema owner is not the database user. Again, ask your database administrator to create public synonyms for the VQWiki tables if this is the case.

If VQWiki doesn't create the tables, check the log files. If there are messages about SQL syntax errors, check the vqwiki.properties file in WEB-INF/classes and the administration console to make sure the database-type is set to "oracle".

Configuration Settings

Admin Console Settings

The Admin Console can be accessed by clicking on the Admin link on any page and entering the Admin password. If the admin password has been lost, see the entry under "Administrator Password Reset" in the Troubleshooting section below.

The Admin Console allows administrators to set the following system parameters:

Table 2.1. Administrative Parameters

Editing lock time-outThe 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 RecentChangesThe number of days back from the present day to display changes made in the RecentChanges list
Maximum number of backlinksAt 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.
Encode passwords in property fileBy default passwords are stored in the property file as plain text. For added security, passwords can be encoded using a DES encryption algorithm by selecting this option.
Automatic index intervalIn 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 breaksThis 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 versioningWhen this is switched off, version backup and diff is not available. This is only recommended where disk space is a real problem.
Allow HTMLWhen this option is switched on, HTML markup will not be ignored, it will be output as HTML.
Allow back-tick WikiNamesWhen 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 usernameWhen this option is on, users must set a username before they are allowed to edit topics.
Format-Lexer, Layout-Lexer and Link-LexerThese are set as fully qualified Java class names. The format lexer is the class responsible for tokenizing the user input and formatting it appropriately - 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 directoryThis 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 limitThis is the maximum allowable file-size in KB, any larger files will be rejected on upload.
Attachment typeThere 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 directoryIn flat-file mode, this is where the files for the wiki topics will be stored.
SMTP host, username and passwordThis 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 addressThis is the address that will appear in the reply-to field for Wiki email notifications.
PersistenceThis is where the persistence mode can be set - either the default "Flat-File", or "Database" to use a 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 does not ship with any JDBC driver, but the default JDBC configuration is for MySQL. See the chapter on MySQL for more information on getting the driver and setting this up.
Closed user group?Normally, a wiki has no closed user group, but anybody is free to enter/modify text. However, in a controlled environment (e.g. inside a company) it may be a requirement, to clearly distinguish the people. Then you can have a closed user group. The wiki can query a data source for the names of that user group. With the selector, you select the type of data source you want to use. Currently, only LDAP is supported. Note: You must have "use versioning" and "Force the setting of username" switched on to see the effects.
Java FactoryThis is the java factory, which is used for the user group. For LDAP choose "com.sun.jndi.ldap.LdapCtxFactory".
URLThe URL to connect to the data source server. For LDAP choose "ldap://your.ldap.server:389".
UsernameThe username you need to connect to the data source. Can be left empty.
PasswordThe password you need to connect to the data source. Can be left empty.
Search-StringThe basic query string you need to query the datasource. For LDAP choose something like "ou=users,dc=yourcompany,dc=com".
Search restrictionsIf you want to add additional restrictions to the search. Use a comma separated list. For LDAP you could do: "objectClass=person"
Name of field of user-idThe name of the field of the user identifier in the datasource. In LDAP it usually is "uid".
Name of field of full nameThe name of the field of the full name in the datasource. In LDAP it usually is "cn".
Name of field of email addressThe name of the field of the email address in the datasource. In LDAP it usually is "mail".
Detailview of user / authorA snippet of HTML code, which is shown on a wiki page to give more details about the author. The text is HTML code plus some placeholders. The placeholders are formatted like "@@cn@@" and are filled with the appropriate field (in the example: the field "cn") from the data source.


The admin console also allows the wiki administrator to perform certain key maintenance functions:

Table 2.2. Administrative Functions

Refresh Search IndexThis forces the flat-file mode search indexer to run. As mentioned earlier, the indexer is run automatically at the interval specified above.
Purge Deleted TopicsThis will delete any topics that contain only the word "delete".
Clear Edit Lock on TopicTo use this, enter a topic name and click the "Go" button, any lock that is held on the topic will be cleared.
Read-only TopicsUse this section to add and remove topics that should be read-only
Add virtual wikiEntering a new virtual wiki name and clicking add will register the virtual wiki of that name. Note that if you want to customize its name in your language you must perform some additional actions. This is covered later in this manual.


Parameters in web.xml

The VQWiki application is constructed as a series of servlets. The mappings for these servlets is controlled by the web.xml file. For most sites, the relevant portion of this file is the portion that controls the provisioning of virtual wikis. See Administrative Tasks : Creating Virtual Wikis, below.

Parameters in properties files

vqwiki.properties

The Admin Console writes the VQWiki system settings to a properties file called vqwiki.properties. This file along with the other configuration files is located by default in {installdir}/WEB-INF/classes. If you edit this file directly, you should restart the vqwiki application to avoid over-writing your updates from the Admin Console, or leaving the system in an inconsistent state.

This file does need to be edited to reset the administrator's password if it is lost. Please see the Administrator's Password Reset in the Troubleshooting section, below.

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="c:/vqwiki" 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>

linking.properties

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/classes/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

externallex.properties

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.

ApplicationResources.properties

Locale-specific language strings. This includes the mail messages to be sent on email notification of topic changes.

mime.types

This file controls what Internet media types are sent to the client for each given file extension(s). Sending the correct media type to the client browser is important so they know how to handle the content of the file. The file follows the format of the standard Apache mime.types file.

This file is primarily useful if you need to support an unusual type of file as an attachment for your Wiki. Simply add the extension and the file type to the end of this file and restart your application.

pseudotopics.properties

This contains key-value mapping of topic names that are not really editable topics to redirect URLs to carry out special actions, e.g. RecentChanges

actions.properties

This contains key-value mapping of action names to class names of classes that implement vqwiki.WikiAction. Plugins place mappings in this file.

Lexers

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.

Another lexer shipped with VQWiki duplicates the syntax used by the popular Mediawiki software (see http://meta.wikimedia.org/wiki/Help:Editing ). To use this lexer the Format lexer value should be set to vqwiki.lex.MediaWikiSyntax, the layout lexer should be set to vqwiki.lex.MediaWikiHTML, and the link lexer should be set to "null".

The lexers that come with VQWiki are generating using the JFlex [4] tool. However, you can write your lexer in any way you choose - so long as it implements the vqwiki.lex.Lexer interface.

Administrative Tasks

Creating Virtual Wikis

VQWiki supports multiple independent wikis on a single webapp instance. These "Virtual Wikis" allow the support of multiple independent content stores. Common applications include public / private wikis, project-specific wikis, and client-specific wikis in a consulting environment. To provision and configure a virtual wiki:

  • Access the admin console

  • Scroll down to the "add virtual wiki" box, enter a name (one word, no spaces), for example "other" and click add

  • Optionally set a "friendly name" for the virtual wiki in {installdir}/WEB-INF/classes/ApplicationResources.properties. The entry should be in the format: virtualwiki.other.name=Other Where "Other" is the name that will appear in the virtual wiki list.

  • You have then to restart the vqwiki webapp to make the "friendly name" visible.

Integrating with LDAP

Normally, a wiki allows anybody to enter and modify text. However, this can create issues in a controlled environment (e.g. inside a company). In order to clearly distinguish the people who are posting, VQWiki supports LDAP connectivity. In order to configure LDAP, access the Admin console, and set the following parameters:

  • Use Versioning - must be checked

  • Force the setting of username - must be checked

  • Closed user group - set to LDAP

  • Java Factory - set to com.sun.jndi.ldap.LdapCtxFactory

  • URL - The URL to connect to the LDAP server. Should be something like "ldap://your.ldap.server:389"

  • Username - The Username to connect to the LDAP server, if required. Can be left blank.

  • Password - The Password to connect to the LDAP server, if required. Can be left blank.

  • Search-String - The basic query string you need to query the datasource. For LDAP choose something like "ou=users,dc=yourcompany,dc=com".

  • Search restrictions - If you want to add additional restrictions to the search. Use a comma separated list. For LDAP you could do: "objectClass=person"

  • Name of field of user-id - The name of the field of the user identifier in the datasource. In LDAP it usually is "uid".

  • Name of field of full name - The name of the field of the full name in the datasource. In LDAP it usually is "cn".

  • Name of field of email address - The name of the field of the email address in the datasource. In LDAP it usually is "mail".

  • Detailview of user / author - A snippet of HTML code, which is shown on a wiki page to give more details about the author. The text is HTML code plus some placeholders. The placeholders are formatted like "@@cn@@" and are filled with the appropriate field (in the example: the field "cn") from the data source.

Maintenance Tasks

Rebuild Search Index

This is only required when using flat-file persistence. Selecting this from the Admin console will trigger a special run of the indexing utility. This is a way to manually run the indexer; it will usually just be allowed to run automatically, as configured by the Automatic Index Interval parameter.

Purge Deleted Topics

Over time, it may be necessary to reorganize and delete outdated topics. This is a two step process:

  • Navigate to the topics to be purged. Edit each topic, replacing all content with the word "delete".

  • Access the Admin Console and select "Purge Deleted Topics".

Note that this deletes the content permanently, and that the historical versions of the file and diffs cannot be recovered after it is performed.

Setting Read-only Topics

VQWiki allows the administrator to set certain topics as read-only. This is useful for controlling key pages (main navigation nodes, etc), or for controlling pages that are subject to frequent vandalism. To mark a page as read only:

  1. Access the Admin Console and log in

  2. Scroll down to "Read-only Topics (jsp)"

  3. Enter the topic name and select "Add"

Troubleshooting

Panic Reset

In the unlikely event that VQWiki begins to misbehave in a significant way, you can attempt a "panic reset" by navigating to the Admin console, logging in, and selecting "Panic Reset" at the bottom of the page.

This effectively stops and restarts the application, which may affect whatever users are doing on the system.

If this fails, try restarting the application context, or the application server itself.

Administrator Password Reset

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 {TOMCAT_HOME}/webapps/vqwiki-2.8.1/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.

Clearing Locks

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 occurring where one user inadvertently overwrites 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 no one 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.

Customizing Look and Feel

Using a Custom Logo

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.

Customizing Page Layouts

VQWiki allows the site administrator to edit the look and feel of the site directly through the application. The governing CSS files as well as the top, left, and bottom menus are all directly editable within the system.

To access these files, Click on the Admin link in the page footer, and login as the administrator. Then, return to the StartingPoints page, and type "AdminOnlyTopics" (without the quotes) into the search box. Click the "Go To" button to see the list of AdminOnlyTopics.

This list should have five elements:

  • LeftMenu - controls the sidebar on the page

  • TopArea - controls the page header area

  • BottomArea - controls the page footer

  • AdminOnlyTopics - controls which topics are editable only by the administrator

  • StyleSheet - the global cascading style sheet in use at the site

Sitewide CSS

The sitewide CSS file can be edited by accessing the AdminOnlyTopics area, as above, and then navigating to the StyleSheet topic. Selecting "Edit" will bring up the page in an editor. It's recommended that you cut and paste the contents from the editor into an external CSS editor, and then reopen the topic once they are completed. This is to avoid inadvertently leaving the wiki in an unusable state while you are working on it.

The CSS file has many class selectors that you can override and edit. Here are some of the most useful:

  • .contents - the main content area of the site

  • .title - the main title area

  • .leftMenu - the sidebar

  • .pageHeader - the name of this topic (within the content area)

  • .navBar - the cookie crumb links at the top of the page

  • .menu - the fixed references above and below the main content area

  • .logo - controls the appearance of the Logo image

  • .searchResult - controls the highlight color of search results

Page headers, footers, left navigation

The left sidebar, page headers, and footers can also be directly edited in the VQWiki environment. Please be cautious; it is possible to make your wiki inoperable if you insert badly formed HTML. In particular, make sure that all HTML is well formed, and that any table or div tags are self-contained and closed.

To edit these files, access them from the AdminOnlyTopics page, as above. Then select the area you are interested in editing, and click the "Edit" button.

The TopArea and BottomArea files are wrapped in special "[<html>][</html>]" tags. There should be one at the beginning of the file and one at the end. These tags are used to signal VQWiki that the following content should be treated as literal HTML. If these tags are not added, then VQWiki will translate the html characters and the raw HTML source will be displayed.

The LeftMenu file is not wrapped in these tags (unless you add them)- this is so the links to pages within the wiki are shown correctly.

Plugins

Plugins add extra functionality to the VQWiki system. A list of plugins is available at http://vqwiki.org/downloads.php. As of this writing, plugins exist to incorporate external RSS feeds and HTML, generate charts, and pretty-printers for HTML and SQL.

Installing Plugins

To install a new plugin in your environment:

  1. Identify your VQWiki file-system directory. This should be set by the "File-system directory" parameter on the admin console.

  2. Stop your vqwiki web application.

  3. Open the file-system directory and look at the files inside. There should be a folder called "plugins".

  4. Place the new downloaded plugin file (as a zip archive) in the plugins folder

  5. Start your vqwiki web application back up

When vqwiki starts up again, the plugins will be unzipped and installed correctly. See the plugin's documentation for specific directions on how to invoke it.

Developing Plugins

If you wish to distribute an external lexer as a plugin, or add new actions, it is possible to package them 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"/>
    <action name="myaction" class="mypackage.MyAction" pseudotopic="MyTopic"/>
</plugin>

This entry will be translated into an entry in externallex.properties and an entry in actions.properties. If a URL is requested from the Wiki controller with an "action" parameter, the value of the action parameter will be looked up as the action name. If a mapping exists, the action class will be instantiated and the HTTP request and response will be forwarded to the action. E.g. http://myserver/wiki/jsp/Wiki?action=myaction will trigger the action in the example above.

The pseudotopic entry on the action element is optional. If present it will associate a pseudotopic with the action. In the case above, going to the topic "MyTopic" will trigger the action, e.g. by navigating to http://myserver/wiki/jsp/Wiki?MyTopic. This is useful if you wish to have the action triggered from a LeftMenu entry for example.

So the entire zip file structure for myplugin.zip should look like:

  • WEB-INF/classes/myplugin.xml

  • WEB-INF/classes/mypackage/MyLexClass.class

  • WEB-INF/classes/mypackage/MyAction.class

Security Issues and Workarounds

VQWiki File Storage Issues

Tomcat UserID

VQWiki stores all files (at least initially) on the local filesystem. If an installation transitions to database persistence, VQWiki continues to use the filesystem for images and other uploaded attachments. This has important security ramifications.

All file access and the initial directory creation are performed as the user that tomcat (or your application server) is running under. This means that if you are running tomcat as root, users will be able to upload files by default to the /root partition, which can be a significant issue on some systems, depending on your partitioning scheme (many systems do not make root subject to disk quotas). Also, files will be assigned to Root ownership, and may be set with root's umask. In a poorly configured system, this could lead to a security breach. It is strongly recommended that you do not run tomcat as root or other privileged user.

The directory that VQWiki writes to is controlled by the parameter "File-system directory" on the Admin console. This directory must be writable by the user that your application server is running under.

Disk Utilization

On a public wiki, a malicious user could create a denial of service attack by uploading many files. At some point, the system will run out of disk space or inodes. In order to prevent this, either set the "File-system directory" parameter on the Admin Console to a location on a separate partition with additional space (eg "/var" on a unix based system), or implement a disk quota system that will prevent the tomcat user from using more space than is planned for your implementation. This should be done with either a database or flat-file persistence system, as images and other attachments are stored on this server.

Archiving Content

Your archiving strategy depends on whether you have configured flatfile or database persistence.

For flatfile users, simply back up your VQWiki file-system directory. This should be set by the "File-system directory" parameter on the admin console.

For database users, you must back up this directory as well as the contents of your database, as the filesystem is used for attached images and other files.

Additionally, it is probably wise to create a snapshot backup of the contents of your {TOMCAT_HOME}/webapps/vqwiki-2.8.1 folder as it will contain configuration settings that may be annoying to replicate at a later time.

Restricting Access

ReadOnly Topics

If a topic is frequently vandalized, it may be advisable to mark it read only. This can be accomplished by an administrator, through the Administrator's console. Please see the section marked "Setting a topic read only" in the "Maintenance Tasks" section, above.

LDAP Authentication

VQWiki allows integration with an external LDAP store. This can be configured so that users are required to authenticate against LDAP before they are allowed to edit topics in the system. Note that anonymous users are still able to view the content on the site. To prevent this, you could try to implement an Apache module like auth_ldap or mod_auth_ldap to look at the same ldap store as VQWiki. In this case, the auth_ldap module in Apache would either allow or disallow viewers and the VQWiki installation itself would either allow or disallow edits.

Note: both Apache and the auth_ldap and mod_auth_ldap modules are not part of the VQWiki installation and as such will not be supported by the project.

LDAP Integration instructions are covered in the LDAP Integration section, above.

Apache Authentication

In order to prevent anonymous users from browsing the content on the site, an authentication system should be enabled at the web tier. If the Apache httpd server is in use, there are a variety of modules that can be used to provide authentication services. While these services will not be directly integrated with VQWiki - an authenticated user will be given access, but no special recognition by the system- they can be used to provide sophisticated access control to the wiki.

A possible usefull method is to use either the auth_ldap or mod_auth_ldap Apache modules to integrate with an LDAP store. See the LDAP Authentication section above.

Detailed Apache documentation is available from http://httpd.apache.org/docs/2.0/howto/auth.html.



[4] JFlex - The Fast Scanner Generator for Java jflex.de

Chapter 3. User's Guide

This chapter is a brief overview of VQWiki from a user's perspective.

What is a Wiki?

Wiki's are loosely organized websites that are designed to make it simple for users to add and edit content on the site. Unlike most websites, Wikis are usually run with very loose permissions; virtually any site user is allowed to come along and edit any page, or to add new pages.

The original Wiki was developed by Ward Cunningham, and called WikiWikiWeb. He based the name on the Hawaiian word "WikiWiki", meaning "Quick". Wikis have grown in popularity, and have been put into use in many different contexts. Within corporations, they are used to allow teams to collaborate more efficiently, and there are a variety of Wikis used to provide documentation for open source software. The most successful wiki is the wikipedia project, which was started to provide a comprehensive encyclopedia using Wiki technologies.

VQWiki Basics

This is what the main VQWiki page looks like when the system is first installed:

Editing a topic

Every individual page in VQWiki is called a "topic". In order to edit a topic, simply navigate to it and look for the link at the bottom of the page titled "EditPage". Clicking on this link will bring up the same topic, with all of the text in a big editable box. Your administrator may have set up the system to require you to provide your name before editing; if your system is set up this way, you'll need to provide your name before continuing.

Simply make your changes inside the box and select "Save" to save your changes. Select Cancel if you don't want to change the topic after all. A few general pointers:

  • Don't press the enter key at the end of a line- let it wrap naturally. People using the Wiki will have their browsers set to different widths, so it's better to let the computer figure out how wide to make each line.

  • Use the enter key to make paragraph breaks

  • The system will make links clickable automatically. Enter in the whole URL (including the http:// part), and the system will make it clickable.

  • If you put in a URL to a graphic (GIF or JPEG), it will be directly included at that point on the page.

Basic Formatting and Markup tags

The Wiki is intended to be quick and easy, so you don't have to learn HTML or a special language to use it. However, there are a few tags you can use to dress up your text:

  • Double Apostrophes (not quotes!) surrounding a word will make it ''italic''.

  • Triple Apostrophes surrounding a word will make it '''bold'''.

  • Triple Plus Double Apostrophes (which is five apostrophes) will make it both '''''bold and italic'''''.

  • To insert a section of code, wrap the code with {{{three curly braces on each side}}}.

  • To underline, put ===Three Equal Signs=== around your text.

  • Double Colons ::Center The Text::

  • If you have a headline, put !!!Three Exclamation Points!!! around it

  • If you have a subhead, put !!Two Exclamation Points!! around it

  • If you have a sub-sub-head, put !One Exclamation Point! around it

  • A dividing line is created with four consecutive dashes ---

Creating a new topic

Creating a topic is a two-part process. First, navigate to a part of the site that should contain a link to your new content. Then, edit that page, and include a link.

A VQWiki link is specified in two ways- either as a CamelCasedWord (a word with embedded capital letters and no spaces), or as a text label surrounded by BackTicks. To insert a link to my page about my model rocket collection, I can either add the text MyModelRockets to the page, or I can add the text `My Model Rockets`.

Once the page containing your new link is saved, you'll see the new text displayed with a question mark at the end- something like "MyModelRockets?". The question mark is actually a hyperlink; clicking on it will bring up a blank page in the text editor, so you can type in your content. After you hit save, the question mark will disappear, and the whole link will become clickable.

Attaching a file or graphic to a topic

If you want to share a document or add an image to a topic, simply navigate to the topic you are interested in, and select "Attach" from the top menu. This will bring up a dialog box that allows you to upload as many as three files at a time. Click on the Browse button to find the files you want to upload, and click on "Save" when you're done. Your administrator probably limited the size of the files that you are allowed to upload, so try to keep them manageable.

Once the file is uploaded, it will appear within the topic's content. If you uploaded an image, the image will be directly included. If you uploaded a document, it will appear as a hyperlink with the same name as the document.

If you want to reference the same image or file in another topic, simply click on "edit this page", and copy the text that linked to the image. It will probably say something like "attach:some_graphics_file.jpg". If you paste this text into another part of the site, it will appear there as well.

Looking at a topic's history

Since a Wiki is usually an environment that anyone can edit, there is significant potential for mischief. In order to fight this, the Wiki stores a copy of each version of each topic when it's saved, so it's easy to revert back to an older version of a given topic. This can also be useful to track the changes that a topic has been through as people contribute to it.

To see the history of a particular topic, first navigate to the topic, and then click on the history item on the page footer. This will bring up a list of the different revisions of the topic. You can see what changed between any versions by selecting their checkboxes, and clicking on the "Diff Selected" button.

Reverting a topic to a previous version

To revert a topic to a previous version, navigate to the topic's main page, and select the History button. Click on the version you are interested in restoring. This will bring up the window in two parts- the top part is the preview of the page, and the bottom part is the raw text. Select and copy the raw text. Then, select the current version link. Once you see the page you wish to replace, click on edit page. Delete the text and replace it with the raw text you copied from the old version of the page.

Advanced VQWiki

VQWiki has many additional features for advanced users. You don't need to know any of this to contribute to the Wiki, but they can definitely help you find information in your wiki, and will allow you to extend the basic functionality of the system.

Special Pages

One of the core concepts in VQWiki is "Special Pages". These look like regular pages in the Wiki, but actually map to functions of the underlying software. This section is a review of each of these special pages. In a default VQWiki installation, these special pages are accessible from links on the left sidebar.

Recent Changes

This is a list of the topics that have been recently changed in the wiki, and either the IP address or the name of the person who performed the modification. Clicking on the link will bring up the page. On a public wiki, it's a good idea to check this periodically, to help prevent abuse- or, to revert it once it happens.

AllWikiTopics

This is a comprehensive list of all of the topics in the Wiki- this includes topics that are used by the administrator to control the look and feel of the wiki. This is a good way to get a feel for the size of the content on your wiki.

Orphaned Wiki Topics

An "orphaned" topic is a topic that doesn't have any other topics that link to it. This means that a user will be unable to navigate through the wiki to find this page- it will only be available through searching the wiki, or through typing the topic name directly. The "AdminOnlyTopics" should probably stay as an orphan, as it is a list of the topics that the local administrator uses to control the look and feel of the system.

ToDoWikiTopics

The Wiki automatically creates links when it encounters a word in CamelCase, or a word surrounded by `backticks`. This is considered a "to-do" item- it's been labeled as a link, but the topic behind it hasn't been created. If you are responsible for the content of the wiki, it is probably a good idea to keep an eye on this page and fill in the blanks where possible- even with simple article stubs. This may inspire other contributors to elaborate- and nothing is more maddening than a wiki that is actually just a bunch of twisty narrow passages, all alike.

Wiki Lock List

As users edit topics on the wiki, individual pages will be locked. You can use this to see how many topics are currently locked and in process of being edited.

Export2HTML

You can save the entire wiki to a set of HTML files and download them for local archiving. The contents of the wiki will appear as a single large ZIP archive, which you can then save to your local hard drive.

Templates

Templates allow you to set up standard text that users can later automatically include in the topics they are editing.

An example would be a software company, that had decided to use VQWiki to keep track of some of their old projects. They want to add a quick description to the wiki for each of their projects. They want to capture standard information for each one, plus whatever additional information team members wanted to add. They start by editing a topic, and simply inserting labels for the information they want to add in: Project Name, Client, Start Date, End Date, Description. Instead of saving the topic, they enter in a name like "project_info" into the box labeled "Save Contents as Template: ". They save the template.

Now when they add a new topic, they can just go to the box labeled "Append Template:", select the "project_info" template, press the Append button. The contents of the template will be copied into the editing area. Now the users have the information we want them to add, the wiki looks more consistent, and they don't have to type it all in again for each project they add.

To change an existing template, append it to a blank topic, edit it as necessary, and simply save it as a template again, using the same name.

Advanced Formatting

VQWiki supports a reasonably rich set of formatting controls. There are some fairly complex controls that only rarely come into play.

  • To create a bulleted list, put in three spaces and an asterisk (*) before each item in the list.

  • To create a numbered list, put three blank spaces and an octothorpe(#) before each item in the list.

  • If you need to create a sub list, put in six spaces, and then either an asterisk or an octothorpe. Keep using multiples of three if you need to continue indenting.

  • If you need to display some characters that the wiki software would read as formatting code, wrap it with two underline characters (for example, __`Backticks that aren't special`__ .

  • On the other hand, if you need to display two underlines in a row for some reason, and you don't want them to turn off your formatting code, escape them with a backslash (like \__ ).

  • If you wish to display preformatted code (like a code sample) and you don't want to use the java pretty-printer described below, insert four "@" signs in a row, followed by your text, followed by a blank line.

  • If you need words to appear in a monospace font inline, wrap them with three braces: {{{your text here}}} .

Links

Any fully qualified URL will be turned into a hotlink. VQWiki contains a number of shortcuts for adding external links to your site.

To use each shortcut, enter in the shortcut, followed by a :, and then the topic you are linking to. For instance, to use the Amazon shortcut, enter in "amazon:020171499X", where "020171499X" is the ISBN number of the book you are linking to. Your administrator can easily define additional shortcuts; many organizations use them to link to bug reports, documents on the internal network, or intranet resources. The default set of shortcuts that comes with VQWiki is:

ShortcutExampleDestination
c2:<topic>c2:GoodStyle<topic> on Ward Cunningham's original wiki
mb:<topic>mb:InformationVisualization<topic> on the UseMod Meatball Wiki
mskd:<number>mskb:256986Displays article <number> in Microsoft's Knowledge Base
edit:<topic>edit:StartingPointsBrings up <topic> in the edit window in this VQWiki installation
redirect:<topic>redirect:StartingPointsRedirects user from one topic to another. Must be the only thing in the body of a topic.
amazon:<isbn>amazon:020171499XLinks to the book with the specified <isbn> on amazon.com
imdb:<number>imdb:0086856Brings up the movie with the specified <number> on the internet movie database.

Embedding HTML

You can put any arbitrary HTML code into a page by simply wrapping it with special [<html>].....[</html>] tags. For example:

[<html>]

<input type="button" value="say hello!" onclick="alert('hello world!')">

[</html>]

Obviously, adding in bad HTML (failing to close a table or div tag) could make it very difficult to edit or repair your page. If that happens, use the page history function to revert to a previous version.

Administrators can disable HTML posting to prevent cross-site scripting attacks through the Administrative control panel.

Embedding Java

You can also embed java code snippets, and the system will format and colorize them appropriately. It works the same way as the html tags above, but with [<java>]...[</java>] tags instead.

[<java>]public void foo() { int a = 5; }[</java>]

Using Plugins

There are a variety of downloadable plugins available for VQWiki. While an administrator must install them, they provide useful features to site authors. Each plugin has it's own documentation, so you are encouraged to review them for yourself. This list is probably out of date; please check http://www.vqwiki.org/downloads.php for updates. As of this writing, known VQWiki plugins included:

Plugin NameLocationDescription
Include http://www.vqwiki.org/plugins/include.zipInclude one topic's content in another.
GetHTML http://www.vqwiki.org/plugins/sqlsrc.zipInclude external web page content in a topic.
SQL Source http://www.vqwiki.org/plugins/sqlsrc.zipPretty-print SQL source code in a topic.
HTML Source http://www.vqwiki.org/plugins/htmlsrc.zipPretty-print HTML source code in a topic.
RSS http://www.vqwiki.org/plugins/rss.zipInclude External RSS feeds in topics.
Chart http://www.vqwiki.org/plugins/chart.zipEasily draw line graphs, bar graphs and pie charts inline in a topic.
BeanShell http://www.vqwiki.org/plugins/beanshell.zipEvaluate Java expressions inline in a topic.
Stats http://www.vqwiki.org/plugins/stats.zipShow simple statistics of changes made by users since server was started. - Intended as a demo of writing a topic listener plugin.
HelloWorld http://www.vqwiki.org/plugins/helloworld.zipShow text output from an action - Intended as a demo of writing an action plugin.

Deleting a Topic

Deleting a topic is very simple; simply replace the contents of the topic with the word "delete". As part of routine maintenance, the administrator will run a cleanup function that will permanently remove the topic from the system.

Elements of Wiki Style

Each Wiki tends to develop its own flavor and personality over time. However, there are a few things that are useful in helping to encourage people to use the system:

  • When working on a topic, review it for opportunities to link to other topics in the system. Users will navigate from link to link, and the richer the link density is, the more rewarding the experience will be.

  • Don't go insane. If every word is a link, nobody is going to have the patience to read through it.

  • Don't leave gaps. If you've created a link, try to at least put in a stub with a preliminary sketch of the subject matter. It's more useful to get a skeleton up and trust to later visitors to put flesh on its bones.

  • Be polite. Don't call people idiots, especially if they are. The Wiki will keep all the old versions of your intemperate outburst available for time imemorial, and your IP address is logged automatically. Reasonable people can and will disagree on almost any topic, and a wiki rewrite war is a huge waste of everyone involved's time.

  • Don't get hung up on formatting. Try to get the information onto the page. The Wiki isn't about creating perfect, polished marketing websites- it's about creating a quick tool for collaboration.

  • Avoid deletions. Instead, if a page is obsolete, consider using a redirect tag to move people to a page that is more relevant. If the topic was created in the first place, there may be external links pointing to it. It's easier on your remote visitors to bring them somewhere useful instead of a confusing blank page.

  • Don't get hung up on structure. A wiki is amorphous, and it will change its shape over time.

  • Watch how users work on the site, and try to come up with templates that they can use to speed up the time it takes to enter new information. It will improve the consistency of the information the wiki captures

  • Use the Minor Edit checkbox if you are correcting typos or other small-scale changes. This stops people gettng notifications when no real changes have happened.

GNU Free Documentation License

Version 1.2, November 2002

Free Software Foundation, Inc. 51 Franklin
        Street, Fifth Floor
 , Boston ,
        MA 02110-1301
        USA

Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

Version 1.2, November 2002

PREAMBLE

The purpose of this License is to make a manual, textbook, or other functional and useful document "free" in the sense of freedom: to assure everyone the effective freedom to copy and redistribute it, with or without modifying it, either commercially or noncommercially. Secondarily, this License preserves for the author and publisher a way to get credit for their work, while not being considered responsible for modifications made by others.

This License is a kind of "copyleft", which means that derivative works of the document must themselves be free in the same sense. It complements the GNU General Public License, which is a copyleft license designed for free software.

We have designed this License in order to use it for manuals for free software, because free software needs free documentation: a free program should come with manuals providing the same freedoms that the software does. But this License is not limited to software manuals; it can be used for any textual work, regardless of subject matter or whether it is published as a printed book. We recommend this License principally for works whose purpose is instruction or reference.

APPLICABILITY AND DEFINITIONS

This License applies to any manual or other work, in any medium, that contains a notice placed by the copyright holder saying it can be distributed under the terms of this License. Such a notice grants a world-wide, royalty-free license, unlimited in duration, to use that work under the conditions stated herein. The "Document", below, refers to any such manual or work. Any member of the public is a licensee, and is addressed as "you". You accept the license if you copy, modify or distribute the work in a way requiring permission under copyright law.

A "Modified Version" of the Document means any work containing the Document or a portion of it, either copied verbatim, or with modifications and/or translated into another language.

A "Secondary Section" is a named appendix or a front-matter section of the Document that deals exclusively with the relationship of the publishers or authors of the Document to the Document's overall subject (or to related matters) and contains nothing that could fall directly within that overall subject. (Thus, if the Document is in part a textbook of mathematics, a Secondary Section may not explain any mathematics.) The relationship could be a matter of historical connection with the subject or with related matters, or of legal, commercial, philosophical, ethical or political position regarding them.

The "Invariant Sections" are certain Secondary Sections whose titles are designated, as being those of Invariant Sections, in the notice that says that the Document is released under this License. If a section does not fit the above definition of Secondary then it is not allowed to be designated as Invariant. The Document may contain zero Invariant Sections. If the Document does not identify any Invariant Sections then there are none.

The "Cover Texts" are certain short passages of text that are listed, as Front-Cover Texts or Back-Cover Texts, in the notice that says that the Document is released under this License. A Front-Cover Text may be at most 5 words, and a Back-Cover Text may be at most 25 words.

A "Transparent" copy of the Document means a machine-readable copy, represented in a format whose specification is available to the general public, that is suitable for revising the document straightforwardly with generic text editors or (for images composed of pixels) generic paint programs or (for drawings) some widely available drawing editor, and that is suitable for input to text formatters or for automatic translation to a variety of formats suitable for input to text formatters. A copy made in an otherwise Transparent file format whose markup, or absence of markup, has been arranged to thwart or discourage subsequent modification by readers is not Transparent. An image format is not Transparent if used for any substantial amount of text. A copy that is not "Transparent" is called "Opaque".

Examples of suitable formats for Transparent copies include plain ASCII without markup, Texinfo input format, LaTeX input format, SGML or XML using a publicly available DTD, and standard-conforming simple HTML, PostScript or PDF designed for human modification. Examples of transparent image formats include PNG, XCF and JPG. Opaque formats include proprietary formats that can be read and edited only by proprietary word processors, SGML or XML for which the DTD and/or processing tools are not generally available, and the machine-generated HTML, PostScript or PDF produced by some word processors for output purposes only.

The "Title Page" means, for a printed book, the title page itself, plus such following pages as are needed to hold, legibly, the material this License requires to appear in the title page. For works in formats which do not have any title page as such, "Title Page" means the text near the most prominent appearance of the work's title, preceding the beginning of the body of the text.

A section "Entitled XYZ" means a named subunit of the Document whose title either is precisely XYZ or contains XYZ in parentheses following text that translates XYZ in another language. (Here XYZ stands for a specific section name mentioned below, such as "Acknowledgements", "Dedications", "Endorsements", or "History".) To "Preserve the Title" of such a section when you modify the Document means that it remains a section "Entitled XYZ" according to this definition.

The Document may include Warranty Disclaimers next to the notice which states that this License applies to the Document. These Warranty Disclaimers are considered to be included by reference in this License, but only as regards disclaiming warranties: any other implication that these Warranty Disclaimers may have is void and has no effect on the meaning of this License.

VERBATIM COPYING

You may copy and distribute the Document in any medium, either commercially or noncommercially, provided that this License, the copyright notices, and the license notice saying this License applies to the Document are reproduced in all copies, and that you add no other conditions whatsoever to those of this License. You may not use technical measures to obstruct or control the reading or further copying of the copies you make or distribute. However, you may accept compensation in exchange for copies. If you distribute a large enough number of copies you must also follow the conditions in section 3.

You may also lend copies, under the same conditions stated above, and you may publicly display copies.

COPYING IN QUANTITY

If you publish printed copies (or copies in media that commonly have printed covers) of the Document, numbering more than 100, and the Document's license notice requires Cover Texts, you must enclose the copies in covers that carry, clearly and legibly, all these Cover Texts: Front-Cover Texts on the front cover, and Back-Cover Texts on the back cover. Both covers must also clearly and legibly identify you as the publisher of these copies. The front cover must present the full title with all words of the title equally prominent and visible. You may add other material on the covers in addition. Copying with changes limited to the covers, as long as they preserve the title of the Document and satisfy these conditions, can be treated as verbatim copying in other respects.

If the required texts for either cover are too voluminous to fit legibly, you should put the first ones listed (as many as fit reasonably) on the actual cover, and continue the rest onto adjacent pages.

If you publish or distribute Opaque copies of the Document numbering more than 100, you must either include a machine-readable Transparent copy along with each Opaque copy, or state in or with each Opaque copy a computer-network location from which the general network-using public has access to download using public-standard network protocols a complete Transparent copy of the Document, free of added material. If you use the latter option, you must take reasonably prudent steps, when you begin distribution of Opaque copies in quantity, to ensure that this Transparent copy will remain thus accessible at the stated location until at least one year after the last time you distribute an Opaque copy (directly or through your agents or retailers) of that edition to the public.

It is requested, but not required, that you contact the authors of the Document well before redistributing any large number of copies, to give them a chance to provide you with an updated version of the Document.

MODIFICATIONS

You may copy and distribute a Modified Version of the Document under the conditions of sections 2 and 3 above, provided that you release the Modified Version under precisely this License, with the Modified Version filling the role of the Document, thus licensing distribution and modification of the Modified Version to whoever possesses a copy of it. In addition, you must do these things in the Modified Version:

GNU FDL Modification Conditions

  1. Use in the Title Page (and on the covers, if any) a title distinct from that of the Document, and from those of previous versions (which should, if there were any, be listed in the History section of the Document). You may use the same title as a previous version if the original publisher of that version gives permission.
  2. List on the Title Page, as authors, one or more persons or entities responsible for authorship of the modifications in the Modified Version, together with at least five of the principal authors of the Document (all of its principal authors, if it has fewer than five), unless they release you from this requirement.
  3. State on the Title page the name of the publisher of the Modified Version, as the publisher.
  4. Preserve all the copyright notices of the Document.
  5. Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.
  6. Include, immediately after the copyright notices, a license notice giving the public permission to use the Modified Version under the terms of this License, in the form shown in the Addendum below.
  7. Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice.
  8. Include an unaltered copy of this License.
  9. Preserve the section Entitled "History", Preserve its Title, and add to it an item stating at least the title, year, new authors, and publisher of the Modified Version as given on the Title Page. If there is no section Entitled "History" in the Document, create one stating the title, year, authors, and publisher of the Document as given on its Title Page, then add an item describing the Modified Version as stated in the previous sentence.
  10. Preserve the network location, if any, given in the Document for public access to a Transparent copy of the Document, and likewise the network locations given in the Document for previous versions it was based on. These may be placed in the "History" section. You may omit a network location for a work that was published at least four years before the Document itself, or if the original publisher of the version it refers to gives permission.
  11. For any section Entitled "Acknowledgements" or "Dedications", Preserve the Title of the section, and preserve in the section all the substance and tone of each of the contributor acknowledgements and/or dedications given therein.
  12. Preserve all the Invariant Sections of the Document, unaltered in their text and in their titles. Section numbers or the equivalent are not considered part of the section titles.
  13. Delete any section Entitled "Endorsements". Such a section may not be included in the Modified Version.
  14. Do not retitle any existing section to be Entitled "Endorsements" or to conflict in title with any Invariant Section.
  15. Preserve any Warranty Disclaimers.

If the Modified Version includes new front-matter sections or appendices that qualify as Secondary Sections and contain no material copied from the Document, you may at your option designate some or all of these sections as invariant. To do this, add their titles to the list of Invariant Sections in the Modified Version's license notice. These titles must be distinct from any other section titles.

You may add a section Entitled "Endorsements", provided it contains nothing but endorsements of your Modified Version by various parties--for example, statements of peer review or that the text has been approved by an organization as the authoritative definition of a standard.

You may add a passage of up to five words as a Front-Cover Text, and a passage of up to 25 words as a Back-Cover Text, to the end of the list of Cover Texts in the Modified Version. Only one passage of Front-Cover Text and one of Back-Cover Text may be added by (or through arrangements made by) any one entity. If the Document already includes a cover text for the same cover, previously added by you or by arrangement made by the same entity you are acting on behalf of, you may not add another; but you may replace the old one, on explicit permission from the previous publisher that added the old one.

The author(s) and publisher(s) of the Document do not by this License give permission to use their names for publicity for or to assert or imply endorsement of any Modified Version.

COMBINING DOCUMENTS

You may combine the Document with other documents released under this License, under the terms defined in section 4 above for modified versions, provided that you include in the combination all of the Invariant Sections of all of the original documents, unmodified, and list them all as Invariant Sections of your combined work in its license notice, and that you preserve all their Warranty Disclaimers.

The combined work need only contain one copy of this License, and multiple identical Invariant Sections may be replaced with a single copy. If there are multiple Invariant Sections with the same name but different contents, make the title of each such section unique by adding at the end of it, in parentheses, the name of the original author or publisher of that section if known, or else a unique number. Make the same adjustment to the section titles in the list of Invariant Sections in the license notice of the combined work.

In the combination, you must combine any sections Entitled "History" in the various original documents, forming one section Entitled "History"; likewise combine any sections Entitled "Acknowledgements", and any sections Entitled "Dedications". You must delete all sections Entitled "Endorsements".

COLLECTIONS OF DOCUMENTS

You may make a collection consisting of the Document and other documents released under this License, and replace the individual copies of this License in the various documents with a single copy that is included in the collection, provided that you follow the rules of this License for verbatim copying of each of the documents in all other respects.

You may extract a single document from such a collection, and distribute it individually under this License, provided you insert a copy of this License into the extracted document, and follow this License in all other respects regarding verbatim copying of that document.

AGGREGATION WITH INDEPENDENT WORKS

A compilation of the Document or its derivatives with other separate and independent documents or works, in or on a volume of a storage or distribution medium, is called an "aggregate" if the copyright resulting from the compilation is not used to limit the legal rights of the compilation's users beyond what the individual works permit. When the Document is included in an aggregate, this License does not apply to the other works in the aggregate which are not themselves derivative works of the Document.

If the Cover Text requirement of section 3 is applicable to these copies of the Document, then if the Document is less than one half of the entire aggregate, the Document's Cover Texts may be placed on covers that bracket the Document within the aggregate, or the electronic equivalent of covers if the Document is in electronic form. Otherwise they must appear on printed covers that bracket the whole aggregate.

TRANSLATION

Translation is considered a kind of modification, so you may distribute translations of the Document under the terms of section 4. Replacing Invariant Sections with translations requires special permission from their copyright holders, but you may include translations of some or all Invariant Sections in addition to the original versions of these Invariant Sections. You may include a translation of this License, and all the license notices in the Document, and any Warranty Disclaimers, provided that you also include the original English version of this License and the original versions of those notices and disclaimers. In case of a disagreement between the translation and the original version of this License or a notice or disclaimer, the original version will prevail.

If a section in the Document is Entitled "Acknowledgements", "Dedications", or "History", the requirement (section 4) to Preserve its Title (section 1) will typically require changing the actual title.

TERMINATION

You may not copy, modify, sublicense, or distribute the Document except as expressly provided for under this License. Any other attempt to copy, modify, sublicense or distribute the Document is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.

FUTURE REVISIONS OF THIS LICENSE

The Free Software Foundation may publish new, revised versions of the GNU Free Documentation License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns. See http://www.gnu.org/copyleft/.

Each version of the License is given a distinguishing version number. If the Document specifies that a particular numbered version of this License "or any later version" applies to it, you have the option of following the terms and conditions either of that specified version or of any later version that has been published (not as a draft) by the Free Software Foundation. If the Document does not specify a version number of this License, you may choose any version ever published (not as a draft) by the Free Software Foundation.

ADDENDUM: How to use this License for your documents

To use this License in a document you have written, include a copy of the License in the document and put the following copyright and license notices just after the title page:

Sample Invariant Sections list

Copyright (c) YEAR YOUR NAME. Permission is granted to copy, distribute and/or modify this document under the terms of the GNU Free Documentation License, Version 1.2 or any later version published by the Free Software Foundation; with no Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A copy of the license is included in the section entitled "GNU Free Documentation License".

If you have Invariant Sections, Front-Cover Texts and Back-Cover Texts, replace the "with...Texts." line with this:

Sample Invariant Sections list

with the Invariant Sections being LIST THEIR TITLES, with the Front-Cover Texts being LIST, and with the Back-Cover Texts being LIST.

If you have Invariant Sections without Cover Texts, or some other combination of the three, merge those two alternatives to suit the situation.

If your document contains nontrivial examples of program code, we recommend releasing these examples in parallel under your choice of free software license, such as the GNU General Public License, to permit their use in free software.

GNU Lesser General Public License

This is the first released version of the Lesser GPL. It also counts as the successor of the GNU Library Public License, version 2, hence the version number 2.1.

Free Software Foundation, Inc. 51 Franklin
        Street, Fifth Floor
 , Boston ,
        MA 02110-1301
        USA

Everyone is permitted to copy and distribute verbatim copies of this license document, but changing it is not allowed.

Version 2.1, February 1999

Preamble

The licenses for most software are designed to take away your freedom to share and change it. By contrast, the GNU General Public Licenses are intended to guarantee your freedom to share and change free software--to make sure the software is free for all its users.

This license, the Lesser General Public License, applies to some specially designated software packages--typically libraries--of the Free Software Foundation and other authors who decide to use it. You can use it too, but we suggest you first think carefully about whether this license or the ordinary General Public License is the better strategy to use in any particular case, based on the explanations below.

When we speak of free software, we are referring to freedom of use, not price. Our General Public Licenses are designed to make sure that you have the freedom to distribute copies of free software (and charge for this service if you wish); that you receive source code or can get it if you want it; that you can change the software and use pieces of it in new free programs; and that you are informed that you can do these things.

To protect your rights, we need to make restrictions that forbid distributors to deny you these rights or to ask you to surrender these rights. These restrictions translate to certain responsibilities for you if you distribute copies of the library or if you modify it.

For example, if you distribute copies of the library, whether gratis or for a fee, you must give the recipients all the rights that we gave you. You must make sure that they, too, receive or can get the source code. If you link other code with the library, you must provide complete object files to the recipients, so that they can relink them with the library after making changes to the library and recompiling it. And you must show them these terms so they know their rights.

We protect your rights with a two-step method:

  1. we copyright the library, and

  2. we offer you this license, which gives you legal permission to copy, distribute and/or modify the library.

To protect each distributor, we want to make it very clear that there is no warranty for the free library. Also, if the library is modified by someone else and passed on, the recipients should know that what they have is not the original version, so that the original author's reputation will not be affected by problems that might be introduced by others.

Finally, software patents pose a constant threat to the existence of any free program. We wish to make sure that a company cannot effectively restrict the users of a free program by obtaining a restrictive license from a patent holder. Therefore, we insist that any patent license obtained for a version of the library must be consistent with the full freedom of use specified in this license.

Most GNU software, including some libraries, is covered by the ordinary GNU General Public License. This license, the GNU Lesser General Public License, applies to certain designated libraries, and is quite different from the ordinary General Public License. We use this license for certain libraries in order to permit linking those libraries into non-free programs.

When a program is linked with a library, whether statically or using a shared library, the combination of the two is legally speaking a combined work, a derivative of the original library. The ordinary General Public License therefore permits such linking only if the entire combination fits its criteria of freedom. The Lesser General Public License permits more lax criteria for linking other code with the library.

We call this license the Lesser General Public License because it does Less to protect the user's freedom than the ordinary General Public License. It also provides other free software developers Less of an advantage over competing non-free programs. These disadvantages are the reason we use the ordinary General Public License for many libraries. However, the Lesser license provides advantages in certain special circumstances.

For example, on rare occasions, there may be a special need to encourage the widest possible use of a certain library, so that it becomes a de-facto standard. To achieve this, non-free programs must be allowed to use the library. A more frequent case is that a free library does the same job as widely used non-free libraries. In this case, there is little to gain by limiting the free library to free software only, so we use the Lesser General Public License.

In other cases, permission to use a particular library in non-free programs enables a greater number of people to use a large body of free software. For example, permission to use the GNU C Library in non-free programs enables many more people to use the whole GNU operating system, as well as its variant, the GNU/Linux operating system.

Although the Lesser General Public License is Less protective of the users' freedom, it does ensure that the user of a program that is linked with the Library has the freedom and the wherewithal to run that program using a modified version of the Library.

The precise terms and conditions for copying, distribution and modification follow. Pay close attention to the difference between a “work based on the library” and a “work that uses the library” . The former contains code derived from the library, whereas the latter must be combined with the library in order to run.

TERMS AND CONDITIONS FOR COPYING, DISTRIBUTION AND MODIFICATION

Section 0

This License Agreement applies to any software library or other program which contains a notice placed by the copyright holder or other authorized party saying it may be distributed under the terms of this Lesser General Public License (also called “this License” ). Each licensee is addressed as “you” .

A “library” means a collection of software functions and/or data prepared so as to be conveniently linked with application programs (which use some of those functions and data) to form executables.

The “Library” , below, refers to any such software library or work which has been distributed under these terms. A “work based on the Library” means either the Library or any derivative work under copyright law: that is to say, a work containing the Library or a portion of it, either verbatim or with modifications and/or translated straightforwardly into another language. (Hereinafter, translation is included without limitation in the term “modification” .)

Source code” for a work means the preferred form of the work for making modifications to it. For a library, complete source code means all the source code for all modules it contains, plus any associated interface definition files, plus the scripts used to control compilation and installation of the library.

Activities other than copying, distribution and modification are not covered by this License; they are outside its scope. The act of running a program using the Library is not restricted, and output from such a program is covered only if its contents constitute a work based on the Library (independent of the use of the Library in a tool for writing it). Whether that is true depends on what the Library does and what the program that uses the Library does.

Section 1

You may copy and distribute verbatim copies of the Library's complete source code as you receive it, in any medium, provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and disclaimer of warranty; keep intact all the notices that refer to this License and to the absence of any warranty; and distribute a copy of this License along with the Library.

You may charge a fee for the physical act of transferring a copy, and you may at your option offer warranty protection in exchange for a fee.

Section 2

You may modify your copy or copies of the Library or any portion of it, thus forming a work based on the Library, and copy and distribute such modifications or work under the terms of Section 1 above, provided that you also meet all of these conditions:

  1. The modified work must itself be a software library.

  2. You must cause the files modified to carry prominent notices stating that you changed the files and the date of any change.

  3. You must cause the whole of the work to be licensed at no charge to all third parties under the terms of this License.

  4. If a facility in the modified Library refers to a function or a table of data to be supplied by an application program that uses the facility, other than as an argument passed when the facility is invoked, then you must make a good faith effort to ensure that, in the event an application does not supply such function or table, the facility still operates, and performs whatever part of its purpose remains meaningful.

    (For example, a function in a library to compute square roots has a purpose that is entirely well-defined independent of the application. Therefore, Subsection 2d requires that any application-supplied function or table used by this function must be optional: if the application does not supply it, the square root function must still compute square roots.)

These requirements apply to the modified work as a whole. If identifiable sections of that work are not derived from the Library, and can be reasonably considered independent and separate works in themselves, then this License, and its terms, do not apply to those sections when you distribute them as separate works. But when you distribute the same sections as part of a whole which is a work based on the Library, the distribution of the whole must be on the terms of this License, whose permissions for other licensees extend to the entire whole, and thus to each and every part regardless of who wrote it.

Thus, it is not the intent of this section to claim rights or contest your rights to work written entirely by you; rather, the intent is to exercise the right to control the distribution of derivative or collective works based on the Library.

In addition, mere aggregation of another work not based on the Library with the Library (or with a work based on the Library) on a volume of a storage or distribution medium does not bring the other work under the scope of this License.

Section 3

You may opt to apply the terms of the ordinary GNU General Public License instead of this License to a given copy of the Library. To do this, you must alter all the notices that refer to this License, so that they refer to the ordinary GNU General Public License, version 2, instead of to this License. (If a newer version than version 2 of the ordinary GNU General Public License has appeared, then you can specify that version instead if you wish.) Do not make any other change in these notices.

Once this change is made in a given copy, it is irreversible for that copy, so the ordinary GNU General Public License applies to all subsequent copies and derivative works made from that copy.

This option is useful when you wish to copy part of the code of the Library into a program that is not a library.

Section 4

You may copy and distribute the Library (or a portion or derivative of it, under Section 2 ) in object code or executable form under the terms of Sections 1 and 2 above provided that you accompany it with the complete corresponding machine-readable source code, which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange.

If distribution of object code is made by offering access to copy from a designated place, then offering equivalent access to copy the source code from the same place satisfies the requirement to distribute the source code, even though third parties are not compelled to copy the source along with the object code.

Section 5

A program that contains no derivative of any portion of the Library, but is designed to work with the Library by being compiled or linked with it, is called a “work that uses the Library” . Such a work, in isolation, is not a derivative work of the Library, and therefore falls outside the scope of this License.

However, linking a “work that uses the Library” with the Library creates an executable that is a derivative of the Library (because it contains portions of the Library), rather than a “work that uses the library” . The executable is therefore covered by this License. Section 6 states terms for distribution of such executables.

When a “work that uses the Library” uses material from a header file that is part of the Library, the object code for the work may be a derivative work of the Library even though the source code is not. Whether this is true is especially significant if the work can be linked without the Library, or if the work is itself a library. The threshold for this to be true is not precisely defined by law.

If such an object file uses only numerical parameters, data structure layouts and accessors, and small macros and small inline functions (ten lines or less in length), then the use of the object file is unrestricted, regardless of whether it is legally a derivative work. (Executables containing this object code plus portions of the Library will still fall under Section 6 .)

Otherwise, if the work is a derivative of the Library, you may distribute the object code for the work under the terms of Section 6 . Any executables containing that work also fall under Section 6 , whether or not they are linked directly with the Library itself.

Section 6

As an exception to the Sections above, you may also combine or link a “work that uses the Library” with the Library to produce a work containing portions of the Library, and distribute that work under terms of your choice, provided that the terms permit modification of the work for the customer's own use and reverse engineering for debugging such modifications.

You must give prominent notice with each copy of the work that the Library is used in it and that the Library and its use are covered by this License. You must supply a copy of this License. If the work during execution displays copyright notices, you must include the copyright notice for the Library among them, as well as a reference directing the user to the copy of this License. Also, you must do one of these things:

  1. Accompany the work with the complete corresponding machine-readable source code for the Library including whatever changes were used in the work (which must be distributed under Sections 1 and 2 above); and, if the work is an executable linked with the Library, with the complete machine-readable “work that uses the Library” , as object code and/or source code, so that the user can modify the Library and then relink to produce a modified executable containing the modified Library. (It is understood that the user who changes the contents of definitions files in the Library will not necessarily be able to recompile the application to use the modified definitions.)

  2. Use a suitable shared library mechanism for linking with the Library. A suitable mechanism is one that (1) uses at run time a copy of the library already present on the user's computer system, rather than copying library functions into the executable, and (2) will operate properly with a modified version of the library, if the user installs one, as long as the modified version is interface-compatible with the version that the work was made with.

  3. Accompany the work with a written offer, valid for at least three years, to give the same user the materials specified in Subsection 6a , above, for a charge no more than the cost of performing this distribution.

  4. If distribution of the work is made by offering access to copy from a designated place, offer equivalent access to copy the above specified materials from the same place.

  5. Verify that the user has already received a copy of these materials or that you have already sent this user a copy.

For an executable, the required form of the “work that uses the Library” must include any data and utility programs needed for reproducing the executable from it. However, as a special exception, the materials to be distributed need not include anything that is normally distributed (in either source or binary form) with the major components (compiler, kernel, and so on) of the operating system on which the executable runs, unless that component itself accompanies the executable.

It may happen that this requirement contradicts the license restrictions of other proprietary libraries that do not normally accompany the operating system. Such a contradiction means you cannot use both them and the Library together in an executable that you distribute.

Section 7

You may place library facilities that are a work based on the Library side-by-side in a single library together with other library facilities not covered by this License, and distribute such a combined library, provided that the separate distribution of the work based on the Library and of the other library facilities is otherwise permitted, and provided that you do these two things:

  1. Accompany the combined library with a copy of the same work based on the Library, uncombined with any other library facilities. This must be distributed under the terms of the Sections above.

  2. Give prominent notice with the combined library of the fact that part of it is a work based on the Library, and explaining where to find the accompanying uncombined form of the same work.

Section 8

You may not copy, modify, sublicense, link with, or distribute the Library except as expressly provided under this License. Any attempt otherwise to copy, modify, sublicense, link with, or distribute the Library is void, and will automatically terminate your rights under this License. However, parties who have received copies, or rights, from you under this License will not have their licenses terminated so long as such parties remain in full compliance.

Section 9

You are not required to accept this License, since you have not signed it. However, nothing else grants you permission to modify or distribute the Library or its derivative works. These actions are prohibited by law if you do not accept this License. Therefore, by modifying or distributing the Library (or any work based on the Library), you indicate your acceptance of this License to do so, and all its terms and conditions for copying, distributing or modifying the Library or works based on it.

Section 10

Each time you redistribute the Library (or any work based on the Library), the recipient automatically receives a license from the original licensor to copy, distribute, link with or modify the Library subject to these terms and conditions. You may not impose any further restrictions on the recipients' exercise of the rights granted herein. You are not responsible for enforcing compliance by third parties with this License.

Section 11

If, as a consequence of a court judgment or allegation of patent infringement or for any other reason (not limited to patent issues), conditions are imposed on you (whether by court order, agreement or otherwise) that contradict the conditions of this License, they do not excuse you from the conditions of this License. If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations, then as a consequence you may not distribute the Library at all. For example, if a patent license would not permit royalty-free redistribution of the Library by all those who receive copies directly or indirectly through you, then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Library.

If any portion of this section is held invalid or unenforceable under any particular circumstance, the balance of the section is intended to apply, and the section as a whole is intended to apply in other circumstances.

It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims; this section has the sole purpose of protecting the integrity of the free software distribution system which is implemented by public license practices. Many people have made generous contributions to the wide range of software distributed through that system in reliance on consistent application of that system; it is up to the author/donor to decide if he or she is willing to distribute software through any other system and a licensee cannot impose that choice.

This section is intended to make thoroughly clear what is believed to be a consequence of the rest of this License.

Section 12

If the distribution and/or use of the Library is restricted in certain countries either by patents or by copyrighted interfaces, the original copyright holder who places the Library under this License may add an explicit geographical distribution limitation excluding those countries, so that distribution is permitted only in or among countries not thus excluded. In such case, this License incorporates the limitation as if written in the body of this License.

Section 13

The Free Software Foundation may publish revised and/or new versions of the Lesser General Public License from time to time. Such new versions will be similar in spirit to the present version, but may differ in detail to address new problems or concerns.

Each version is given a distinguishing version number. If the Library specifies a version number of this License which applies to it and “any later version” , you have the option of following the terms and conditions either of that version or of any later version published by the Free Software Foundation. If the Library does not specify a license version number, you may choose any version ever published by the Free Software Foundation.

Section 14

If you wish to incorporate parts of the Library into other free programs whose distribution conditions are incompatible with these, write to the author to ask for permission. For software which is copyrighted by the Free Software Foundation, write to the Free Software Foundation; we sometimes make exceptions for this. Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally.

NO WARRANTY Section 15

BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY FOR THE LIBRARY, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES PROVIDE THE LIBRARY “AS IS” WITHOUT WARRANTY OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE LIBRARY IS WITH YOU. SHOULD THE LIBRARY PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

Section 16

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE LIBRARY (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.

END OF TERMS AND CONDITIONS

How to Apply These Terms to Your New Libraries

If you develop a new library, and you want it to be of the greatest possible use to the public, we recommend making it free software that everyone can redistribute and change. You can do so by permitting redistribution under these terms (or, alternatively, under the terms of the ordinary General Public License).

To apply these terms, attach the following notices to the library. It is safest to attach them to the start of each source file to most effectively convey the exclusion of warranty; and each file should have at least the “copyright” line and a pointer to where the full notice is found.

<one line to give the library's name and a brief idea of what it does.> Copyright (C) <year> <name of author>

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA

Also add information on how to contact you by electronic and paper mail.

You should also get your employer (if you work as a programmer) or your school, if any, to sign a “copyright disclaimer” for the library, if necessary. Here is a sample; alter the names:

Yoyodyne, Inc., hereby disclaims all copyright interest in the library `Frob' (a library for tweaking knobs) written by James Random Hacker.

<signature of Ty Coon>, 1 April 1990 Ty Coon, President of Vice

That's all there is to it!