for release 2.7.x
VQWiki version 2.7.7 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:< support@vqwiki.org>
Copyright © 2001-2006 The VQWiki Project
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/.
Table of Contents
- Preface
- 1. About VQWiki
- 2. Administrator's Guide
- 3. VQWiki User's Guide
- A. GNU Free Documentation License
- B. GNU Lesser General Public License
List of Tables
- 1.1. Conventions
- 2.1. Administrative Parameters
- 2.2. Administrative Functions
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]
[1] DocBook at Oasis http://www.oasis-open.org/docbook/
[2] DocBook Open Repository http://docbook.sourceforge.net/
Table of Contents
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.
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.war", the default local URL for Tomcat will be
http://localhost:8080/vqwiki |
{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 |
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
Changes for version 2.7.7
TO BE FILLED IN
Previous changes are available at http://vqwiki.org/docs/whatsnew.txt
| Project Lead | Martijn van der Kleijn |
| Developers | Martijn van der Kleijn, Andreas Studer, Colin Jacobs, Tobias Schulz-Hess, Fritz Freiheit, Gareth Cronin |
| Documentation | Tim Howland |
| Translation Maintainers | |
| Italian | Marcello Teodori |
| Spanish | Zapo (erzapo) |
| German | Nico Jabin |
| Swedish | Johan Lindell |
| Norwegian | Erik |
| French | <position vacant> |
| Polish | Michael (mindweb) |
| Dutch | Martijn van der Kleijn |
| English | Martijn van der Kleijn |
| Non-project Contributors: | Fabrizio Zellini, Fritz Kunstler |
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.
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: VQWiki User's Guide - Guide to Wikis in general, and specific features of VQWiki
This document will be available from the VQWiki website at http://www.vqwiki.org.
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://croninsolutions.com/mailman/listinfo/vqwiki-users_croninsolutions.com
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.
Table of Contents
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.3.1 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 4.1.24 and JDK 1.4.X[3]
Users have also reported successful implementation with the following servlet containers:
Apache Tomcat 5.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.
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.7.x
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 Remediation.
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.7.x.war. The name of the
WAR file may be different in which case you should substitute your WAR
file name for vqwiki-2.7.x.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.7.x, 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.7.x
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 for access to administrative functions. Memorize the 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 administrative functions where you can customise VQWiki. 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 Remediation.
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; see below for Oracle-specific notes.
To use database persistence, you must start by creating a database instance for vqwiki, as well as provisioning a userID 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. 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 userid and password should not be used for security reasons.
VQWiki will generate it's 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 (org.gjt.mysql.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.
If you are using a database other than mysql, you may need to put the database's JDBC drivers into a location that VQWiki can access. For a development system, it may be simplest to download the JDBC drivers that are designed for your database, and copy them to
{$TOMCAT_HOME}/webapps/VQWiki-2.7.x/lib/. You should also obtain the JDBC driver name and URL format from the documentation at the developer's website.Similarly, using a very recent version of MySQL may also require using an updated version of the MySQL drivers. Download and install them as above.
Once 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.
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.
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.
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}/shared/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://otn.oracle.com/software/tech/java/sqlj_jdbc/content.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
${TOMCAT_HOME}/webapps/vqwiki-2.7.x/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".
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-out | The number of minutes that a user can edit a topic for exclusively. After this time out, another user may begin to edit the topic, and should this occur, the user whose edit timed-out will have to redo their changes. |
| Number of days of RecentChanges | The number of days back from the present day to display changes made in the RecentChanges list |
| Maximum number of backlinks | At the bottom of every page a list of links to topics that link to the current topic is displayed. If the topic is mentioned often, this list can grow very large. The maximum backlink limit keeps this list to the specified number. If the number is exceeded, a "..." appears after the list. A user can always check on all the backlinks by clicking on the topic title to perform a search on the title term. |
| Automatic index interval | In the default flat-file mode, the search index is updated every time a topic is altered, this picks up any additions to topics, however it does not account for removal of terms that have been deleted from topic text. A periodic sweep of the text needs to be made to account for deletions. This interval is the amount of time between sweeps. 24 hours should really be sufficient, due to the fact that Wiki is by nature additive rather than subtractive. |
| New line breaks | This controls how many HTML breaks are inserted for every new line in the edited text. The default is 2, but some people prefer one line to equal one line, in which case this can be set to 1. |
| Use versioning | When this is switched off, version backup and diff is not available. This is only recommended where disk space is a real problem. |
| Allow HTML | When this option is switched on, HTML markup will not be ignored, it will be output as HTML. |
| Allow back-tick WikiNames | When this option is on, back-tick wiki-naming is allowed. With the option off, only traditional CamelCaps naming can be used. |
| Force the setting of username | When this option is on, users must set a username before they are allowed to edit topics. |
| Format-Lexer, Layout-Lexer and Link-Lexer | These are set as fully qualified Java class names. The format lexer is the class responsible for tokenizing the user input and formatting it 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 directory | This can either be a relative or an absolute path. If
it is relative, it will be created relative to the
{installdir}. Ensure that if you
are using Windows, you specify the path with Unix-style
forward slashes ("/"), not the DOS-style backslashes. The
directory specified by the path will be used to store file
upload attachments. |
| File upload size limit | This is the maximum allowable file-size in KB, any larger files will be rejected on upload. |
| Attachment type | There are two ways to deliver attachments to users. "Inline" will ask the browser to open the file itself, e.g. with a plug-in as for Adobe Acrobat. It will do this in a new window. "Attachment" asks the browser to show a download prompt immediately. It really depends on how you use attachments as to which is preferable for your users. It is also very much up to the browser how it deals with the requests, so behaviour will differ across different browsers. |
| File-system directory | In flat-file mode, this is where the files for the wiki topics will be stored. |
| SMTP host, username and password | This is the SMTP host name or IP address for the server that will handle outgoing email for topic change notifications. The username and password can be left blank for non-authenticating SMTP servers. |
| Reply address | This is the address that will appear in the reply-to field for Wiki email notifications. |
| Persistence | This is where the persistence mode can be set - either the default "Flat-File", or "Database" to use a MySQL database as the back end. If you select "Database", you will be presented with further fields in which to enter the JDBC database driver name, the database name and a user and password. VQWiki ships with the MM MySQL driver and its name will be the default value. See the chapter on MySQL for more information on setting this up. |
| 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 Factory | This is the java factory, which is used for the user group. For LDAP choose "com.sun.jndi.ldap.LdapCtxFactory". |
| URL | The URL to connect to the data source server. For LDAP choose "ldap://your.ldap.server:389". |
| Username | The username you need to connect to the data source. Can be left empty. |
| Password | The password you need to connect to the data source. Can be left empty. |
| 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. |
The admin console also allows the wiki administrator to perform certain key maintenance functions:
Table 2.2. Administrative Functions
| Refresh Search Index | This forces the flat-file mode search indexer to run. As mentioned earlier, the indexer is run automatically at the interval specified above. |
| Purge Deleted Topics | This will delete any topics that contain only the word "delete". |
| Clear | Edit Lock on Topic To use this, enter a topic name and click the "Go" button, any lock that is held on the topic will be cleared. |
| Read-only Topics | Use this section to add and remove topics that should be read-only |
| Add virtual wiki | Entering a new virtual wiki name and clicking add will register the virtual wiki of that name. Note that a servlet mapping must be added to the web-app descriptor as well. This is covered later in this manual. |
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.
The VQWiki.properties file contains many internal-only configuration settings. In most cases, these settings are identical to those configured by the administrative console. If you must edit this file directly, you should restart the vqwiki application context or the entire application server immediately to avoid over-writing your updates, 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.
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
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.
Locale-specific language strings. This includes the mail messages to be sent on email notification of topic changes.
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.
This file controls the Debugging level of the system. The
first line should be set to "WARN", eg:
log4j.rootLogger=WARN, A1 Set this to DEBUG
to generate detailed application logs if you are having trouble- but
do not set it to DEBUG in production, as it will severely impact
performance (and generate large logfiles).
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
VQWiki supports multiple independent wikis on a single application server. 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) and click add
Shut down your application server
Edit
${TOMCAT_HOME}/webapps/VQWiki-2.7.x/WEB-INF/web.xmlYou'll find a sample mapping and a comment for setting up a new Wiki servlet mapping
Add a mapping to the Wiki servlet using the same name as you chose in step 2 as the part of the URL after the base Wiki context. E.g. if your virtual wiki is called "other", the complete mapping will look like:
<servlet-mapping><servlet-name>Wiki</servlet-name><url-pattern>/other/Wiki</url-pattern></servlet-mapping>Set a "friendly name" for the virtual wiki in
${TOMCAT_HOME}/webapps/VQWiki-2.7.x/WEB-INF/ApplicationResources.properties. The entry should be of the format: virtualwiki.other.name=Other Where "Other" is the name that will appear in the virtual wiki list.
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.
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.
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.
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:
Access the Admin Console and log in
Scroll down to "Read-only Topics (jsp)"
Enter the topic name and select "Add"
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.
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.7.x/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.
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.
The custom logo image feature works as follows:
By default, we use
{installdir}/images/logo.jpg. If the user
specifies the URL of an alternate image in the deployment metadata,
that image will be used instead. In this case, a "Powered by VQWiki"
image will be displayed on the footer of all pages that use the custom
logo.
E.g., in Tomcat server.xml, it would look like this (note the override attribute):
<Context path="" docBase="vqwiki-classic" debug="0"
> <env-entry>
<description>logoImageName</description>
<env-entry-name>logoImageName</env-entry-name>
<env-entry-value>/images/tomcat-power.png</env-entry-value>
<env-entry-type>java.lang.String</env-entry-type>
</env-entry> </Context>
or
<Context path="/vqwiki/mikewiki"
docBase="vqwiki-classic" debug="0" > <Environment
name="logoImageName" type="java.lang.String"
value="http://images.sourceforge.net/head_bg_new.gif"
override="false"/> </Context>
The index page and admin console still display the VQWiki logo, as always.
VQWiki 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
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
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 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.
To install a new plugin in your environment:
Identify your VQWiki file-system directory. This should be set by the "File-system directory" parameter on the admin console.
Shut down your application server.
Open the file-system directory and look at the files inside. There should be a folder called "Plugins"
Place the new downloaded plugin file (as a zip archive) in the plugins folder
Start the application server back up
When the server starts up again, the plugins will be unzipped and installed correctly. See the plugin's documentation for specific directions on how to invoke it.
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.
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.
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.7.x folder
as it will contain configuration settings that may be annoying to
replicate at a later time.
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.
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.
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.
Table of Contents
This chapter is a brief overview of VQWiki from a user's perspective..
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.
This is what the main VQWiki page looks like when the system is first installed:
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.
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 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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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}}}.
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:
| Shortcut | Example | Destination |
|---|---|---|
| c2:<topic> | c2:GoodStyle | <topic> on Ward Cunningham's original wiki |
| mb:<topic> | mb:InformationVisualization | <topic> on the UseMod Meatball Wiki |
| mskd:<number> | mskb:256986 | Displays article <number> in Microsoft's Knowledge Base |
| edit:<topic> | edit:StartingPoints | Brings up <topic> in the edit window in this VQWiki installation |
| redirect:<topic> | redirect:StartingPoints | Redirects user from one topic to another. Must be the only thing in the body of a topic. |
| amazon:<isbn> | amazon:020171499X | Links to the book with the specified <isbn> on amazon.com |
| imdb:<number> | imdb:0086856 | Brings up the movie with the specified <number> on the internet movie database. |
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.
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 Name | Location | Description |
|---|---|---|
| Include | http://www.vqwiki.org/plugins/include.zip | Include one topic's content in another. |
| GetHTML | http://www.vqwiki.org/plugins/sqlsrc.zip | Include external web page content in a topic. |
| SQL Source | http://www.vqwiki.org/plugins/sqlsrc.zip | Pretty-print SQL source code in a topic. |
| HTML Source | http://www.vqwiki.org/plugins/htmlsrc.zip | Pretty-print HTML source code in a topic. |
| RSS | http://www.vqwiki.org/plugins/rss.zip | Include External RSS feeds in topics. |
| Chart | http://prdownloads.sourceforge.net/veryquickwiki/chart.zip?download | Easily draw line graphs, bar graphs and pie charts inline in a topic. |
| BeanShell | http://prdownloads.sourceforge.net/veryquickwiki/beanshell.zip?download | Evaluate Java expressions inline in a topic. |
| Stats | http://prdownloads.sourceforge.net/veryquickwiki/stats.zip?download | Show simple statistics of changes made by users since server was started. - Intended as a demo of writing a topic listener plugin. |
| HelloWorld | http://prdownloads.sourceforge.net/veryquickwiki/helloworld.zip?download | Show text output from an action - Intended as a demo of writing an action plugin. |
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.
Version 1.2, November 2002
Copyright © 2000, 2001, 2002 Free Software Foundation, Inc.
Version 1.2, November 2002
Table of Contents
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.
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.
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.
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.
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
- 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.
- 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.
- State on the Title page the name of the publisher of the Modified Version, as the publisher.
- Preserve all the copyright notices of the Document.
- Add an appropriate copyright notice for your modifications adjacent to the other copyright notices.
- 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.
- Preserve in that license notice the full lists of Invariant Sections and required Cover Texts given in the Document's license notice.
- Include an unaltered copy of this License.
- 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.
- 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.
- 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.
- 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.
- Delete any section Entitled "Endorsements". Such a section may not be included in the Modified Version.
- Do not retitle any existing section to be Entitled "Endorsements" or to conflict in title with any Invariant Section.
- 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 co