move all documentation into a directory

doc/README.Install.md

@@ -0,0 +1,396 @@
+SeedDMS Installation Instructions
+==================================
+
+NOTE FOR VERSION 4.0.0
+======================
+
+Since version 4.0.0 of SeedDMS installation has been simplified. 
+ADOdb is no longer needed because the database access is done by
+PDO.
+
+IMPORTANT NOTE ABOUT TRANSLATIONS
+=================================
+
+As you can see SeedDMS provides a lot of languages but we are not professional 
+translators and therefore rely on user contributions.
+
+If your language is not present in the login panel:
+- copy the language/English/ folder and rename it appropriately for your
+  language
+- open the file `languages/your_lang/lang.inc` and translate it
+- open the help file `languages/your_lang/help.htm` and translate it too
+
+If you see some wrong or not translated messages:
+- open the file `languages/your_lang/lang.inc`
+- search the wrong messages and translate them
+
+if you have some "error getting text":
+- search the string in the english file `languages/english/lang.inc`
+- copy to your language file `languages/your_lang/lang.inc`
+- translate it
+
+If there is no help in your language:
+- Copy the English help `english/help.htm` file to your language folder
+- translate it
+
+If you apply any changes to the language files please send them to the
+SeedDMS developers <info@seeddms.org>.
+
+http://www.iana.org/assignments/language-subtag-registry has a list of
+all language and country codes.
+
+REQUIREMENTS
+============
+
+SeedDMS is a web-based application written in PHP. It uses the MySQL RDBMS
+or sqlite3 to manage the documents that were uploaded into the application.
+
+Make sure you have PHP 5.3 and MySQL 5 or higher installed. SeedDMS
+will work with PHP running in CGI-mode as well as running as module under
+apache. If you want to give your users the opportunity of uploading passport
+photos you have to enable the gd-library (but the rest of SeedDMS will
+work without gd, too).
+
+Here is a detailed list of requirements:
+
+1. A web server with at least php 5.3
+2. A mysql database, unless you use sqlite
+3. The php installation must have support for `pdo_mysql` or `pdo_sqlite`,
+   `php_gd2`, `php_mbstring`
+4. Various command line programms to convert files into text for indexing
+   pdftotext, catdoc, xls2csv or scconvert, cat, id3 (optional, only needed
+   for fulltext search)
+5. ImageMagic (the convert program) is needed for creating preview images 
+6. The Zend Framework (version 1) (optional, only needed for fulltext search)
+7. The pear Log package
+8. The pear HTTP_WebDAV_Server package (optional, only need for webdav)
+9. SLIM RestApi
+10. FeedWriter from https://github.com/mibe/FeedWriter
+
+
+BEFORE YOU START
+================
+
+SeedDMS has changed its installation process with version 3.0.0. This gives
+you many more options in how to install SeedDMS. First of all, SeedDMS was
+split into a core package (`SeedDMS_Core-<version>.tar.gz`) and the web
+application itself (`seeddms-<version>.tar.gz`). The core is a pear package
+which could be installed as one. It is responsible for all the database
+operations. The web application contains the ui not knowing anything about
+the database layout. Second, one SeedDMS installation can be used for
+various customer instances by sharing a common source. Starting with
+version 3.2.0 a full text search engine has been added. This requires
+the zend framework and another pear package `SeedDMS_Lucene-<version>.tar.gz`
+which can be downloaded from the SeedDMS web page. Version 4.0.0 show
+preview images of documents which requires `SeedDMS_Preview-<version>.tar.gz`.
+Finally, SeedDMS has
+got a web based installation, which takes care of most of the installation
+process.
+
+Before you proceed you have to decide how to install SeedDMS:
+1. with multiple instances
+2. as a single instance
+
+Both have its pros and cons, but
+1. setting up a single instance is easier if you have no shell access to
+   the web server
+2. the installation script is only tested for single instances
+
+Installation for multiple instances shares the same source by many
+instances but requires to create links which is not in any case possible
+on your web server.
+
+0. Some preparation
+-------------------
+
+A common source of problems in the past have been the additional software
+packages needed by SeedDMS. Those are the PEAR packages `Log` and
+`HTTP_WebDAV_Server` as well as the `Zend_Framework`.
+If you have full access to the server running a Linux distribution it is
+recommended to install those with your package manager if they are provided
+by your Linux distribution. If you cannot install it this way then choose
+a directory (preferable not below your web document root), unpack the
+software into it and extend the php include path with your newly created
+directory. Extending the php include can be either done by modifying
+php.ini or adding a line like
+
+> php_value include_path '/home/mypath:.:/usr/share/php'
+
+to your apache configuration or setting the `extraPath` configuration
+variable of SeedDMS.
+
+For historical reasons the path to the SeedDMS_Core and SeedDMS_Lucene package
+can still be set
+in the configuration, which is not recommend anymore. Just leave those
+parameters empty.
+
+On Linux/Unix your web server should be run with the environment variable
+LANG set to your system default. If LANG=C, then the original filename
+of an uploaded document will not be preserved if the filename contains
+non ascii characters.
+
+Turn off magic_quotes_gpc in your php.ini, if you are using a php version
+below 5.4.
+
+1. Using the installation tool
+------------------------------
+
+Unpack seeddms-<version>.tar.gz below the document root of
+your web server.
+Install `SeedDMS_Preview-<version>.tar.gz` and
+`SeedDMS_Core-<version>.tar.gz` either as a regular pear package or
+set up a file system structure like pear did somewhere on you server.
+For the full text search engine support, you will also
+need to install `SeedDMS_Lucene-<version>.tar.gz`.
+
+For the following instructions we will assume a structure like above
+and seeddms-<version> being accessible through
+http://localhost/seeddms/
+
+* Point you web browser towards http://hostname/seeddms/install/
+
+* Follow the instructions on the page and create a file `ENABLE_INSTALL_TOOL`
+  in the conf directory.
+
+* Create a data directory with the thre sub directories staging, cache
+  and lucene.
+  Make sure the data directory is either *not* below your document root
+	or is protected with a .htaccess file against web access. The data directory
+  needs to be writable by the web server.
+
+* Clicking on 'Start installation' will show a form with all necessary
+  settings for a basic installation.
+
+* After saving your settings succesfully you are ready to log in as admin and
+  continue customizing your installation with the 'Admin Tools'
+
+2. Detailed installation instructions (single instance)
+-------------------------------------------------------
+
+You need a working web server with MySQL/PHP5 support and the files
+`SeedDMS-<version>.tar.gz`, `SeedDMS_Preview-<version>.tar.gz` and
+`SeedDMS_Core-<version>.tgz`. For the 
+full text search engine support, you will also need to unpack
+`SeedDMS_Lucene-<version>.tgz`.
+
+* Unpack all the files in a public web server folder. If you're working on
+  a host machine your provider will tell you where to upload the files.
+  If possible, do not unpack the pear packages `SeedDMS_Core-<version>.tgz`,
+	`SeedDMS_Preview-<version>.tgz` and
+  `SeedDMS_Lucene-<version>.tgz` below the document root of your web server.
+	Choose a temporary folder, as the files will be moved in a second.
+
+  Create a directory e.g. `pear` in the same directory where you unpacked
+  seeddms and create a sub directory SeedDMS. Move the content except for the
+  `tests` directory of all SeedDMS pear
+  packages into that directory. Please note that `pear/SeedDMS` may not 
+  (and for security reasons should not) be below your document root.
+  
+  You will end up with a directory structure like the following
+
+  > seeddms-<version>
+  > pear
+  >   SeedDMS
+  >     Core.php
+  >     Core
+  >     Lucene.php
+  >     Lucene
+  >     Preview
+  >     Preview.php
+
+  Since they are pear packages they can also be installed with
+
+	> pear install SeedDMS_Core-<version>.tgz
+	> pear install SeedDMS_Lucene-<version>.tgz
+	> pear install SeedDMS_Preview-<version>.tgz
+
+* The PEAR package Log is also needed. It can be downloaded from
+  http://pear.php.net/package/Log. Either install it as a pear package
+	or place it under your new directory 'pear'
+
+  > pear
+	>   Log
+	>   Log.php
+
+* The package HTTP_WebDAV_Server is also needed. It can be downloaded from
+  http://pear.php.net/package/HTTP_WebDAV_Server. Either install it as a
+	pear package or place it under your new directory 'pear'
+
+  > pear
+  >   HTTP
+	>     WebDAV
+	>       Server
+	>       Server.php
+
+  If you run PHP in CGI mode, you also need to place a .htaccess file
+	in the webdav directory with the following content.
+
+	RewriteEngine on
+	RewriteRule .* - [env=HTTP_AUTHORIZATION:%{HTTP:Authorization},last]
+
+* Create a data folder somewhere on your web server including the subdirectories
+  staging, cache and lucene and make sure they are writable by your web server,
+  but not accessible through the web.
+
+For security reason the data folder should not be inside the public folders
+or should be protected by a .htaccess file. The folder containing the
+configuration (settings.xml) must be protected by an .htaccess file like the
+following.
+
+	> <Files ~ "^settings\.xml">
+	> Order allow,deny
+	> Deny from all
+	> </Files>
+
+
+If you install SeedDMS for the first time continue with the database setup.
+
+* Create a new database on your web server
+  e.g. for mysql:
+	create database seeddms;
+* Create a new user for the database with all permissions on the new database
+  e.g. for mysql:
+	grant all privileges on seeddms.* to seeddms@localhost identified by 'secret';
+	(replace 'secret' with you own password)
+* Optionally import `create_tables-innodb.sql` in the new database
+  e.g. for mysql:
+	> cat create_tables-innodb.sql | mysql -useeddms -p seeddms
+  This step can also be done by the install tool.
+* create a file `ENABLE_INSTALL_TOOL` in the conf directory and point
+  your browser at http://hostname/seeddms/install
+
+
+NOTE: UPDATING FROM A PREVIOUS VERSION OR SEEDDMS
+
+As SeedDMS is a smooth continuation of LetoDMS there is no difference
+in updating from LetoDMS or SeedDMS
+
+- make a backup archive of your installation folder
+- make a backup archive of your data folder
+- dump your current database
+- extract the SeedDMS archive to your web server
+- edit the conf/settings.xml file to match your previuos settings 
+  (you can even replace the file with your own one eventualy adding by hand
+  the missing new parameters)
+- create a file `ENABLE_INSTALL_TOOL` in the conf directory and point
+  your browser at http://hostname/seeddms/install
+
+The install tool will detect the version of your current SeedDMS installation
+and run the required database updates.
+
+
+3. Email Notification
+---------------------
+
+A notification system allows users to receive an email when a
+document or folder is changed. This is an event-based mechanism that
+notifies the user as soon as the change has been made and replaces the
+cron mechanism originally developed. Any user that has read access to a
+document or folder can subscribe to be notified of changes. Users that
+have been assigned as reviewers or approvers for a document are
+automatically added to the notification system for that document.
+
+A new page has been created for users to assist with the management of
+their notification subscriptions. This can be found in the "My Account"
+section under "Notification List".
+
+
+4. Nearly finished
+------------------
+
+Now point your browser to http://hostname/seeddms/index.php
+and login with "admin" both as username and password.
+After having logged in you should first choose "My Account" and
+change the Administrator's password and email-address.
+
+
+CONFIGURING MULTIPLE INSTANCES
+==============================
+
+Since version 3.0.0, SeedDMS can be set up to run several parallel instances
+sharing the same source but each instance has its own configuration. This is
+quite useful if you intend to host SeedDMS for several customers. This
+approach still allows to have diffenrent version of SeedDMS installed
+and will not force you to upgrade a customer instance, because other
+instances are upgraded. A customer instance consists of
+1. a directory containing mostly links to the SeedDMS source and a
+   configuration file
+2. a directory containing the document content files
+3. a database
+
+1. Unpack the SeedDMS distribution
+----------------------------------
+
+Actually there is no need to set up the database at this point but it won't
+hurt since you'll need one in the next step anyway. The sources of SeedDMS
+can be anywhere you like. The do not have to be in you www-root. If you just
+have access to your www-root directory, then put them there.
+
+2. Setup the instance
+---------------------
+
+Unpack the files as described in the quick installation.
+
+Create a directory in your www-root or use www-root for your instance. In the
+second case, you will not be able to create a second instance, because each
+instance needs its own directory.
+
+Go into that directory create the following links (<seeddms-source> is the
+directory of your initial SeedDMS intallation).
+
+> src -> <seeddms-source>
+> inc -> src/inc
+> op -> src/op
+> out -> src/out
+> js -> src/js
+> views -> src/views
+> languages -> src/languages
+> styles -> src/styles
+> themes -> src/themes
+> install -> src/install
+> index.php -> src/index.php
+
+> ln -s ../seeddms-<version> src
+> ln -s src/inc inc
+> ln -s src/op op
+> ln -s src/out out
+> ln -s src/js js
+> ln -s src/views views
+> ln -s src/languages languages
+> ln -s src/styles styles
+> ln -s src/themes themes
+> ln -s src/install install
+> ln -s src/index.php index.php
+
+Create a new directory named conf and run the installation tool.
+
+Creating the links as above has the advantage that you can easily switch
+to a new version and go back if it is necessary. You could even run various
+instances of SeedDMS using different versions.
+
+3. Create a database and data store for each instance
+-----------------------------------------------------
+
+Create a database and data store for each instance and adjust the database
+settings in conf/settings.xml or run the installation tool.
+
+Point your web browser towards the index.php file in your new instance.
+
+LICENSING
+=========
+
+SeedDMS is licensed unter GPLv2
+
+Jumploader is licensed as stated by the author on th web site
+<http://jumploader.com/>
+
+-- Taken from web site of jumploader  ---
+You may use this software for free, however, you should not:
+
+- Decompile binaries.
+- Alter or replace class and/or resource files.
+- Redistribute this software under different name or authority.
+
+If you would like a customized version, I can do this for a fee. Don't hesitate to contact me with questions or comments.
+
+Uwe Steinmann <info@seeddms.org>

doc/README.Notification

@@ -0,0 +1,114 @@
+Notifications
+-----------------------------------------------
+
+Most changes made to documents or folders in SeedDMS can be monitored
+by the users. Notifications are send by email if a user or group
+has subscribed it.
+
+The following notifications are send to all users and groups having
+registered a notification for the event:
+
+op/op.AddDocument.php
+op/op.AddMultiDocument.php
+* adding a new document to a folder
+  subscribers of the parent folder
+
+op/op.AddSubFolder.php
+* adding a new subfolder to a folder
+  subscribers of the parent folder
+
+op/op.AddFile2.php
+op/op.AddFile.php
+* adding a new file to a document
+  subscribers of the document
+
+op/op.ApproveDocument.php
+* approval status has changed
+  subscribers of the document
+
+op/op.DocumentAccess.php
+* access rights or ownership has changed
+  subscribers of the document
+
+op/op.DocumentNotify.php
+* document notification was changed
+  owner or group of the document/notification
+
+op/op.EditComment.php
+* document's comment has been changed
+  subscribers of the document
+
+op/op.EditDocument.php
+* document has been changed
+  subscribers of the document
+
+op/op.EditFolder.php
+* folder has been changed
+  subscribers of the folder
+
+op/op.FolderAccess.php
+* access rights or ownership has changed
+  subscribers of the folder
+
+op/op.FolderNotify.php
+* folder notification was changed
+  owner or group of the folder/notification
+
+op/op.ManageNotify.php
+* notification was removed
+  owner of the notification
+
+op/op.MoveDocument.php
+* document was moved
+  subscribers of the document
+
+op/op.MoveFolder.php
+* folder was moved
+  subscribers of the folder
+
+op/op.OverrideContentStatus.php
+
+op/op.RemoveDocumentFile.php
+* file of document was removed
+  subscribers of the document
+
+op/op.RemoveDocument.php
+* document was removed
+  subscribers of the document
+
+op/op.RemoveFolder.php
+* folder was removed
+  subscribers of the folder
+
+op/op.RemoveVersion.php
+* version of document was removed
+  subscribers of the document
+
+op/op.RemoveWorkflowFromDocument.php
+* Workflow has been removed from document version
+  subscribers of the document
+
+op/op.ReturnFromSubWorkflow.php
+* Subworkflow has been ended and parent workflow will be continued
+  subscribers of the document
+
+op/op.ReviewDocument.php
+* document was reviewed
+  subscribers of the document
+
+op/op.RewindWorkflow.php
+* Workflow was rewind to beginning
+  subscribers of the document
+
+op/op.RunSubWorkflow.php
+* Subworkflow was started
+  subscribers of the document
+
+op/op.TriggerWorkflow.php
+* Workflow transition was triggered
+  subscribers of the document
+
+op/op.UpdateDocument2.php
+op/op.UpdateDocument.php
+* document was updated
+  subscribers of the document

doc/README.ReviewApproval.md

@@ -0,0 +1,39 @@
+Review/Approval
+------------------
+
+The traditional Review/Approval process has been around for a long time
+already and is still available, though the new workflow engine has been
+introduced.
+
+Review/Approval is a very simple, but in many cases sufficient, workflow
+to review and approve document versions. Review and approval is done by users
+in behalf of themself or the group they belong to. A document version
+is reviewed or approved if all users and groups in charge of it, have
+found the document version to be ready and worth for release. If a single
+user rejects it, it will not change its status to 'released' but to 'rejected'.
+
+Review is always done before approval, but a document version may not have 
+to run through both processes.
+A version can use just the approval process without a review before,
+and it can also skip the approval process and just run through review. In
+the second case the document will be released immidiately after successful
+review.
+
+If a group is in charge for reviewing/approving a document, it will be
+sufficient if one member of that group takes action.
+
+Internally SeedDMS keeps a record of all approval/review actions done on
+a document version. When a document version is uploaded with both processes
+in place, then for each user/group a list of log entries is created. Any
+action on the document will add a new entry to the log. Those entries
+contain the action (release/reject), a user comment and the current date.
+Each entry will also trigger an internal function which checks, whether
+the last action causes a document state change. Such a state change happens
+when all reviews or approvals are done, or if a review/approval is rejected.
+If a user or a group is deleted and some documents are still waiting for
+a review/approval, this will also be logged and the review/approval will
+no longer be needed to release the document.
+
+Before a document leaves the approval or review state any review/approval
+or reject can be changed. So if a user initially approves a document and
+later changes her/his mind, he/she can still reject the document.

doc/README.Ubuntu

@@ -0,0 +1,143 @@
+This README was written by Eric Smith
+
+======================================================
+Steps that I took to install SeedDMS on Ubuntu 12.10
+- a personal account and not an authoritative guide.
+======================================================
+
+Download four tar balls from;
+http://sourceforge.net/projects/seeddms/files/seeddms-4.0.0-pre5/
+
+seeddms-4.0.0-pre5.tar.gz
+SeedDMS_Preview-1.0.0.tgz
+SeedDMS_Lucene-1.1.1.tgz
+SeedDMS_Core-4.0.0pre5.tgz
+
+Install as follows the pear components:
+sudo pear install SeedDMS_Core-4.0.0pre5.tgz
+sudo pear install SeedDMS_Preview-1.0.0.tgz
+sudo pear install SeedDMS_Lucene-1.1.1.tgz
+
+Download and install the pear Log application:
+wget http://download.pear.php.net/package/Log-1.12.7.tgz
+sudo pear install Log-1.12.7.tgz
+
+And zend:
+sudo pear channel-discover zend.googlecode.com/svn
+sudo pear install zend/zend
+
+I installed the following packages, not all of which may be required
+and you may require other packages, please check the dependencies on
+the README.md for example for full text search, you need pdftotext,
+catdoc, xls2csv or scconvert, cat, id3 
+
+sudo apt-get install php5-mysql php5-mysqlnd libapache2-mod-php5
+sudo apt-get install pdo_mysql php5-gd id3 scconvert
+sudo apt-get install php-http-webdav-server
+sudo apt-get install zend-framework zend-framework-bin
+sudo apt-get install libzend-framework-zendx-php
+sudo apt-get install libjs-dojo-core libjs-dojo-dijit libjs-dojo-dojox
+sudo apt-get install libzend-framework-php (It kept bitching about Zend so I just kept piling on packages until it worked)
+
+mbstring is already a part of libapache2-mod-php5
+pepper:~> show libapache2-mod-php5|grep mbstring
+ mbstring mhash openssl pcre Phar posix Reflection session shmop SimpleXML
+ 
+
+Define three locations:
+[1] Some cosy place in yourfile system for the source files to which you
+will link
+I chose "/opt/seeddms-4.0.0-pre5/"
+untar seeddms-4.0.0-pre5.tar.gz into this location
+
+[2] Make a directory and three subdirectories for the data for your site;
+I chose to do this under "/opt/dms/seeddms_multisite_test/data"
+sudo mkdir -p /opt/dms/seeddms_multisite_test/data/lucene/
+sudo mkdir /opt/dms/seeddms_multisite_test/data/staging/
+sudo mkdir /opt/dms/seeddms_multisite_test/data/cache/
+
+Give ownership (or write access) to your httpd process to those directories;
+sudo chown -cvR  www-data  /opt/dms/seeddms_multisite_test/data/
+
+[3] Somewhere under your www root, make a directory for the sources of
+your site:
+These can be of course under different virtual domains.
+/var/www/www.mydomain.eu/seeddms_multisite_test 
+cd /var/www/www.mydomain.eu/seeddms_multisite_test; 
+sudo ln -s /opt/seeddms-4.0.0-pre5 src (README.md does not include the `src'!)
+ln -s src/inc inc
+ln -s src/op op
+ln -s src/out out
+ln -s src/js js
+ln -s src/views views
+ln -s src/languages languages
+ln -s src/styles styles
+ln -s src/themes themes
+ln -s src/install install
+ln -s src/index.php index.php
+
+If need be;
+sudo chown -cvR  www-data /var/www/www.mydomain.eu/seeddms_multisite_test/
+
+Create Dataabse;
+Run the following sql commands to create your db and a user with
+appropriate privileges.
+
+mysql> create database seeddms_multisite_test;
+mysql> grant all privileges on seeddms_multisite_test.* to seeddms@localhost identified by 'your_passwd';
+
+
+Point your browser to the  location of your instance as in [3] above
+and /install
+I resorted to a text browser on my server due to failure to access the
+db from a remote browser;
+
+pepper:~> elinks www.mydomain.eu/seeddms_multisite_test/install
+
+This is how I filled it in;
+                                                            SeedDMS: INSTALL
+   SeedDMS Installation for version 4.0.0
+
+   Server settings
+   Root directory:                /opt/seeddms-4.0.0-pre5/_______________________
+   Http Root:                     /seeddms_multisite_test/_______________________
+   Content directory:             /opt/dms/seeddms_multisite_test/data___________
+   Directory for full text index: /opt/dms/seeddms_multisite_test/data/lucene/___
+   Directory for partial uploads: /opt/dms/seeddms_multisite_test/data/staging/__
+   Core SeedDMS directory:        _______________________________________________
+   Lucene SeedDMS directory:      _______________________________________________
+   Extra PHP include Path:        _______________________________________________
+   Database settings
+   Database Type:                 mysql________________
+   Server name:                   localhost____________
+   Database:                      seeddms_multisite_tes
+   Username:                      seeddms______________
+   Password:                      ********_____________
+   Create database tables:        [X]
+
+   [ Apply ]
+
+
+If all is okay (and I hope this happens more quickly for you than for me),
+you should be notified accordingly and invited to login to your new site
+with credentials admin/admin. (This password is cleverly set to expire
+in a couple of days. So do not get a shock like I did when it suddenly
+does not work).
+
+-------------------------------------------------------------------------------
+
+To make additional sites;
+
+If you wish to make additional sites, you need to copy the data directories thusly;
+sudo cp -avr  /opt/dms/seeddms_multisite_test /opt/dms/seeddms_multisite_test_2
+And the sources thusly;
+sudo cp -avr /var/www/www.mydomain.eu/seeddms_multisite_test /var/www/www.mydomain.eu/seeddms_multisite_test_2
+
+And of course make data directories for this site:
+sudo mkdir -p /opt/dms/seeddms_multisite_test_2/data/lucene/
+sudo mkdir /opt/dms/seeddms_multisite_test_2/data/staging/
+sudo mkdir /opt/dms/seeddms_multisite_test_2/data/cache/
+
+Then create another database as shown above but of course give the db
+another name.
+Run the install again from the new location.

doc/README.Workflow

@@ -0,0 +1,89 @@
+Workflows in SeedDMS
+====================
+
+SeedDMS supports approval and review of documents for a long time.
+In many cases this is sufficient for a simple workflow management.
+Nevertheless there was growing demand for a more powerful document
+workflow. Since version 4.0.0 SeedDMS allows to define arbitrary
+workflows for each document content. In order to understand how
+workflows in SeedDMS work, one has to understand how a workflow is modelled.
+Let's start with a definition of some terms.
+
+workflow: a list of document states and transitions. A workflow starts
+  in a preset initial state and traverses along the transitions into other
+  states until no more transitions are possible.
+
+state: the current status of a document (actually a document content)
+  A state can be for example 'rejected', 'approved', 'waiting for qm'.
+  Document jump from state to state when transitions are fired.
+  States are the nodes of a graph.
+
+transition: a transition is the change from one state to a new state
+  Transitions are the edges of a graph. A transition can only be
+  triggered by a given list of users and groupѕ, when a defined action
+  is run. Such an action can be 'approve', 'revise', 'reject', etc.
+  transitions may need more than one trigger to fire, e.g. if several
+  users have to approve a document.
+
+trigger a transition: a user runs an action on the document which possibly
+  changes the state. Internally this is identical to triggering a transition.
+  Such a trigger may or may not change the state of the document,
+  because there could
+  be other users which also have to trigger the transition.
+  After each trigger of an transition it will
+  be checked whether all conditions are met to change the state.
+  Triggers are currently only implemented for user interaction, but
+  other triggers could be added.
+
+action: the actual operation run on the document. Each transition has
+  an action which when run, triggers the transition. Actions have just a name.
+
+sub workflow: The modelling of a workflow is identical to a regular
+  workflow. Any workflow can be used as a sub workflow. Branching into
+  a sub workflow is only possible if the current state is equal to the
+  initial state of the sub workflow and the user is allowed to trigger
+  the next transition in the current workflow.
+
+A workflow and a sub workflow are just a list
+of transitions and an initial state. There is no principal difference
+between the two and they are equally modelled. Starting from an initial state
+there are a number of possible transitions ending in a new state. Each
+transition can only be triggered if the user has the right to do so.
+
+A workflow can be assigned to a document just like any other attribute
+if the user has sufficient rights. Once a workflow is assigned, the document
+will be in the initial state of the workflow. As long as the workflow
+has not left its initial state, it can be removed from the document by
+any users with write permission on the document. Once it has left the
+initial state it cannot be removed without rewinding the workflow to
+its initial state. Rewinding the workflow will remove the log of triggered
+transitions and set the document status on the initial state of the
+workflow. Rewinding can only be done by administrators.
+
+The purpose of sub workflows is to replace a transition with more
+states in between. Such a case can happen, if approval or rejection
+of a document is put in charge of a group of persons, e.g. a department.
+If the department head decides to set up its own workflow within his
+department, he can run a sub workflow. During the lifetime of the sub
+workflow, the former workflow (parent workflow) will be paused. Sub workflows
+can only be started if the current document state is equal to the initial
+state of the sub workflow.
+In order to return to the parent workflow two conditions must be met:
+1. the state of the document must be a valid state in the parent workflow
+2. the person initiating the return to the parent workflow must be allowed
+   to trigger the transition which was replaced by the sub workflow
+The second condition requires all end states in the sub workflow, also
+being a state in the parent workflow. Currently this is not checked before
+entering the sub workflow.
+
+A workflow that was accidently added to a document can be removed
+as long as it is still in the initial state of the workflow. Once
+a transition into a consecutive state has happemed the workflow cannot
+be removed anymore. In such a case the administrator has to rewind
+the workflow, which removes all triggers including the users comments
+and resets the initial state. The same procedure is true for sub workflows
+as well. Once a sub workflow has started it can only be left as long
+as it is in its initial state or has reached a state in the parent
+workflow. Leaving a workflow inbetween will required to rewind it to
+the begining and dismiss all transitions done so far.
+