source/doc/README_FOR_APP - epf/org.eclipse.epf.wiki - Git at Google

 = About EPF Wiki
 EPF Wiki is Wiki technology designed to be used together with Eclipse Process Framework (EPF). This offers the best of two distinct worlds: the worlds powerful process frameworks and Wikis. It offers an process engineering infrastructure that combines a modular method construction approach and the flexibility and ease of use that is the defining characteristic of a Wiki.

 EPF Wiki is an innovation that adds wiki functions to the hypertext process descriptions created with EPF.

 More information:
 * {Data model}[link:files/doc/DATAMODEL.html]
 * {EPF Wiki Infrastructure}[link:files/doc/INFRASTRUCTURE.html]
 * {Code Statistics}[link:../stats.txt]
 * {Change Log}[link:files/CHANGELOG.html]

 = Version
 * Application version: $VERSION$
 * Buildid: $BUILDID$

 = Features
 * <b>Browser Based HTML Editing</b>: edit existing pages or create new pages using a browser
 * <b>Edit/Info link</b>: to edit a page, simply click on the 'Edit/Info' link at the top of each page
 * <b>Linking pages</b>: links to pages can be created or edited using dialog boxes
 * <b>WYSIWYG or HTML editing</b>: choice of two HTML editors: 1) TinyMCE (open-source) or 2) PinEdit (commercial) and TinyMCE
 * <b>Wikis</b>: support for multiple Wikis with the possibility of sharing content between Wikis
 * <b>Revision Control</b>: all changes to pages are tracked, revisions can be retrieved, differences analyzed, who change what and when
 * <b>Access Control</b>: simple authorization mechanism based on two groups: administrators and users
 * <b>File attachments</b>: upload files (for instance templates, examples)
 * <b>Search</b>: full text search
 * <b>Managing users:</b> web based user registration and change of password
 * <b>Difference Analysis</b>: compare successive baseline processes (created with EPF): what is new, removed, changed, equal.

 = Requirements
 * Ruby 1.8.4
 * Ruby Gems 0.9.0
 * Rails 1.1.6
 * A database that is supported by Rails migrations
 * Ruby drivers for your database.
 * For best performance, you should have a web server running either Apache or Lighttpd along with FastCGI, you can use the built-in web server for low-volume testing
 * TinyMCE[http://tinymce.moxiecode.com] or PinEdit[http://pinedit.pintexx.com/] and TinyMCE
 * Python and the Python script <tt>html2text.py</tt>
 * CSDiff.exe
 * 1) PinEdit and TinyMCE or 2) TinyMCE
 * Apache Ant
 * Windows
 * acces to an SMTP server as users register using email


 = Installation

 Server installation consists of the following steps:

 1. Install Ruby and Ruby Gems
 2. Install Ruby On Rails
 3. Install Ruby Gems
 4. Generate RoR skeleton and extract downloaded epfwiki_R$VERSION$_$BUILDID$.zip
 5. Install Python & script html2text.py
 6. Edit config files: add database information and SMTP server
 7. Install EPF Wiki database schema
 8. Install HTML editor: PinEdit and/or TinyMCE
 9. Install diff tool: CSDiff
 10. path in dispatch.rb
 11. test the configuration

 <b>1. Install Ruby and Ruby Gems</b>

 Download and install Ruby from http://www2.ruby-lang.org/en/. Download and install Ruby Gems from http://www.rubygems.org/

 <b>2. Install Ruby On Rails</b>

 Open a command prompt, navigate to Ruby Gems directory (for instance C:\rubygems-0.9.0) and type <tt>gem install rails</tt>. If you are behind a proxy you can type for example <tt>gem install rails -p yourproxy</tt>

 For more information about gem install type <tt>gem help install</tt>

 <b>3. Install Ruby Gems</b>

 The following Ruby Gems are used:

 1. Tidy (tidy-1.1.2.gem[http://rubyforge.vm.bytemark.co.uk/gems/tidy-1.1.2.gem])
 2. MySQL (mysql-2.7.1-mswin32.gem[http://rubyforge.vm.bytemark.co.uk/gems/mysql-2.7.1-mswin32.gem])
 3. Search Generator (search_generator-0.5.1.gem[http://rubyforge.vm.bytemark.co.uk/gems/search_generator-0.5.1.gem])

 These can be installed with the following commands:
 - gem install tidy
 - gem install mysql
 - gem install search_generator

 Note: Ruby Gems can be installed using command <tt>gem install</tt> or can be installed manually by downloading the gems from http://gems.rubyforge.org/. Your proxy server can be specified using p switch, for more information type <tt>gem help install</tt>

 Note: the Tidy Gem is just a wrapper, the dll needs is a separate download. Download from http://tidy.sf.net and unzip to U:\ROR\epfwiki2\lib\tidy. The tidy folder should now contain three folders bin, include, lib. This location is specified by the environment variable EPFWIK_TIDY_PATH.

 <b>4. Generate RoR skeleton and extract downloaded epfwiki_R$VERSION$_$BUILDID$.zip</b>

 Generate a RoR skeleton using command <tt>rails epfwiki</tt>. Extra the contents of the zip file to the generate folder 'epfwiki', overwrite existing files.

 <b>5. Install Python & script html2text.py</b>

 Install Python 2.4 and html2text.py. html2text.py can be downloaded from http://www.aaronsw.com/2002/html2text/. Place this script in the directory script\other next to the file html2text.bat. To avoid Unicode encoding errors find the file <tt>site.py</tt> in the Python directory and set the encoding var to <tt>utf_8</tt> (look for 'encoding = ' in the file)

 So this version uses a Python script <tt>html2text.py</tt> to turn HTML into markdown text. This is used for difference analyses. The script is not part of this distribution and will in time be replaced by a Ruby alternative.

 <b>6. Edit config files: add database information and SMTP server</b>
 Create one or more databases (depending on the environments you want to setup: test, development and/or production). Edit the database configuration file (database.yml) and add the details of your database(s).

 For each environment (production, test, development) you want to use, edit the corresponding configuration file (in the config/environments folder). At a minimum you should specify the details of your SMTP server (address, port, domain)

 <b>7. Install EPF Wiki database schema</b>

 After creating the databases run the command <tt>rake migrate</tt> from your application root.

 <b>8. Install HTML editor: PinEdit and/or TinyMCE</b>

 _TinyMCE_
 1. Download TinyMCE from tinymce.moxiecode.com[http://tinymce.moxiecode.com/download.php]
 2. Extract the contents and copy the folder tinymce\jscripts\tiny_mce to [application install dir]\public\javascripts. The folder javascripts\tinymce should now contain Javascript library <tt>tiny_mce.js</tt>
 3. config.php
 For more information see http://www.busyashell.com/blog/articles/2006/06/23/using-tinymce-in-rails

 _PinEdit_
 1. Edit PinEdit config file (<tt>editor/config/config.js</tt>): at a minimum specify <tt>globalRootUrl</tt> and <tt>globalRootPath</tt>
 2. Edit <tt>public\editor\dialogs\php\upload.html</tt>, in <tt>beforeSubmit</tt> method set the action, for instance <tt>document.frmUpload.action = "../../../pages/upload?path=" + pathabs + "&insert=" + insert;</tt>

 <b>9. Install diff tool: CSDiff</b>

 Download CSDiff from http://www.componentsoftware.com/Products/CSDiff/download.htm. Note: this is only free software for single users. Extract the software to <tt>[RAILS_APP_ROOT]\script\other\CSDiff</tt>, for instance <tt>c:/epfwiki/script/other/CSDiff<tt>. Add the path to the 'path' environment variable.

 <b>10. path in dispatch.rb</b>

 Change the 'require' in <tt>dispatch.rb</tt> ('public' folder) to match the location of the application.

 <b>11. test the configuration</b>

 At this point it is possible to test the configuration by starting the built-in web server by running the command <tt>ruby script/server -b localhost -e development -p 3000</tt> and navigating to the location http://localhost:3000. This should now bring up the form for creating the first account (the central admininstrators account)

 = Copyright
 Copyright (c) 2006 LogicaCMG and others

 All rights reserved. This program and the accompanying materials
 are made available under the terms of the Eclipse Public License v1.0
 which accompanies this distribution, and is available at
 http://www.eclipse.org/legal/epl-v10.html

 Contributors:
 * Onno van der Straaten:: initial implementation
	= About EPF Wiki
	EPF Wiki is Wiki technology designed to be used together with Eclipse Process Framework (EPF). This offers the best of two distinct worlds: the worlds powerful process frameworks and Wikis. It offers an process engineering infrastructure that combines a modular method construction approach and the flexibility and ease of use that is the defining characteristic of a Wiki.

	EPF Wiki is an innovation that adds wiki functions to the hypertext process descriptions created with EPF.

	More information:
	* {Data model}[link:files/doc/DATAMODEL.html]
	* {EPF Wiki Infrastructure}[link:files/doc/INFRASTRUCTURE.html]
	* {Code Statistics}[link:../stats.txt]
	* {Change Log}[link:files/CHANGELOG.html]

	= Version
	* Application version: $VERSION$
	* Buildid: $BUILDID$

	= Features
	* <b>Browser Based HTML Editing</b>: edit existing pages or create new pages using a browser
	* <b>Edit/Info link</b>: to edit a page, simply click on the 'Edit/Info' link at the top of each page
	* <b>Linking pages</b>: links to pages can be created or edited using dialog boxes
	* <b>WYSIWYG or HTML editing</b>: choice of two HTML editors: 1) TinyMCE (open-source) or 2) PinEdit (commercial) and TinyMCE
	* <b>Wikis</b>: support for multiple Wikis with the possibility of sharing content between Wikis
	* <b>Revision Control</b>: all changes to pages are tracked, revisions can be retrieved, differences analyzed, who change what and when
	* <b>Access Control</b>: simple authorization mechanism based on two groups: administrators and users
	* <b>File attachments</b>: upload files (for instance templates, examples)
	* <b>Search</b>: full text search
	* <b>Managing users:</b> web based user registration and change of password
	* <b>Difference Analysis</b>: compare successive baseline processes (created with EPF): what is new, removed, changed, equal.

	= Requirements
	* Ruby 1.8.4
	* Ruby Gems 0.9.0
	* Rails 1.1.6
	* A database that is supported by Rails migrations
	* Ruby drivers for your database.
	* For best performance, you should have a web server running either Apache or Lighttpd along with FastCGI, you can use the built-in web server for low-volume testing
	* TinyMCE[http://tinymce.moxiecode.com] or PinEdit[http://pinedit.pintexx.com/] and TinyMCE
	* Python and the Python script <tt>html2text.py</tt>
	* CSDiff.exe
	* 1) PinEdit and TinyMCE or 2) TinyMCE
	* Apache Ant
	* Windows
	* acces to an SMTP server as users register using email


	= Installation

	Server installation consists of the following steps:

	1. Install Ruby and Ruby Gems
	2. Install Ruby On Rails
	3. Install Ruby Gems
	4. Generate RoR skeleton and extract downloaded epfwiki_R$VERSION$_$BUILDID$.zip
	5. Install Python & script html2text.py
	6. Edit config files: add database information and SMTP server
	7. Install EPF Wiki database schema
	8. Install HTML editor: PinEdit and/or TinyMCE
	9. Install diff tool: CSDiff
	10. path in dispatch.rb
	11. test the configuration

	<b>1. Install Ruby and Ruby Gems</b>

	Download and install Ruby from http://www2.ruby-lang.org/en/. Download and install Ruby Gems from http://www.rubygems.org/

	<b>2. Install Ruby On Rails</b>

	Open a command prompt, navigate to Ruby Gems directory (for instance C:\rubygems-0.9.0) and type <tt>gem install rails</tt>. If you are behind a proxy you can type for example <tt>gem install rails -p yourproxy</tt>

	For more information about gem install type <tt>gem help install</tt>

	<b>3. Install Ruby Gems</b>

	The following Ruby Gems are used:

	1. Tidy (tidy-1.1.2.gem[http://rubyforge.vm.bytemark.co.uk/gems/tidy-1.1.2.gem])
	2. MySQL (mysql-2.7.1-mswin32.gem[http://rubyforge.vm.bytemark.co.uk/gems/mysql-2.7.1-mswin32.gem])
	3. Search Generator (search_generator-0.5.1.gem[http://rubyforge.vm.bytemark.co.uk/gems/search_generator-0.5.1.gem])

	These can be installed with the following commands:
	- gem install tidy
	- gem install mysql
	- gem install search_generator

	Note: Ruby Gems can be installed using command <tt>gem install</tt> or can be installed manually by downloading the gems from http://gems.rubyforge.org/. Your proxy server can be specified using p switch, for more information type <tt>gem help install</tt>

	Note: the Tidy Gem is just a wrapper, the dll needs is a separate download. Download from http://tidy.sf.net and unzip to U:\ROR\epfwiki2\lib\tidy. The tidy folder should now contain three folders bin, include, lib. This location is specified by the environment variable EPFWIK_TIDY_PATH.

	<b>4. Generate RoR skeleton and extract downloaded epfwiki_R$VERSION$_$BUILDID$.zip</b>

	Generate a RoR skeleton using command <tt>rails epfwiki</tt>. Extra the contents of the zip file to the generate folder 'epfwiki', overwrite existing files.

	<b>5. Install Python & script html2text.py</b>

	Install Python 2.4 and html2text.py. html2text.py can be downloaded from http://www.aaronsw.com/2002/html2text/. Place this script in the directory script\other next to the file html2text.bat. To avoid Unicode encoding errors find the file <tt>site.py</tt> in the Python directory and set the encoding var to <tt>utf_8</tt> (look for 'encoding = ' in the file)

	So this version uses a Python script <tt>html2text.py</tt> to turn HTML into markdown text. This is used for difference analyses. The script is not part of this distribution and will in time be replaced by a Ruby alternative.

	<b>6. Edit config files: add database information and SMTP server</b>
	Create one or more databases (depending on the environments you want to setup: test, development and/or production). Edit the database configuration file (database.yml) and add the details of your database(s).

	For each environment (production, test, development) you want to use, edit the corresponding configuration file (in the config/environments folder). At a minimum you should specify the details of your SMTP server (address, port, domain)

	<b>7. Install EPF Wiki database schema</b>

	After creating the databases run the command <tt>rake migrate</tt> from your application root.

	<b>8. Install HTML editor: PinEdit and/or TinyMCE</b>

	_TinyMCE_
	1. Download TinyMCE from tinymce.moxiecode.com[http://tinymce.moxiecode.com/download.php]
	2. Extract the contents and copy the folder tinymce\jscripts\tiny_mce to [application install dir]\public\javascripts. The folder javascripts\tinymce should now contain Javascript library <tt>tiny_mce.js</tt>
	3. config.php
	For more information see http://www.busyashell.com/blog/articles/2006/06/23/using-tinymce-in-rails

	_PinEdit_
	1. Edit PinEdit config file (<tt>editor/config/config.js</tt>): at a minimum specify <tt>globalRootUrl</tt> and <tt>globalRootPath</tt>
	2. Edit <tt>public\editor\dialogs\php\upload.html</tt>, in <tt>beforeSubmit</tt> method set the action, for instance <tt>document.frmUpload.action = "../../../pages/upload?path=" + pathabs + "&insert=" + insert;</tt>

	<b>9. Install diff tool: CSDiff</b>

	Download CSDiff from http://www.componentsoftware.com/Products/CSDiff/download.htm. Note: this is only free software for single users. Extract the software to <tt>[RAILS_APP_ROOT]\script\other\CSDiff</tt>, for instance <tt>c:/epfwiki/script/other/CSDiff<tt>. Add the path to the 'path' environment variable.

	<b>10. path in dispatch.rb</b>

	Change the 'require' in <tt>dispatch.rb</tt> ('public' folder) to match the location of the application.

	<b>11. test the configuration</b>

	At this point it is possible to test the configuration by starting the built-in web server by running the command <tt>ruby script/server -b localhost -e development -p 3000</tt> and navigating to the location http://localhost:3000. This should now bring up the form for creating the first account (the central admininstrators account)

	= Copyright
	Copyright (c) 2006 LogicaCMG and others

	All rights reserved. This program and the accompanying materials
	are made available under the terms of the Eclipse Public License v1.0
	which accompanies this distribution, and is available at
	http://www.eclipse.org/legal/epl-v10.html

	Contributors:
	* Onno van der Straaten:: initial implementation