Manual for "RefactorDW"
============================
http://www.digitalcure.org
"RefactorDW" is a Java-based tool designed to help to migrate from Dokuwiki to Confluence wiki, as the existing UWC (universal wiki converter) provided by Atlassian
lacks of certain functionality regarding Dokuwiki migration. Apart from that it may be used to perform some refactoring tasks upon Dokuwiki pages without the intention to
migrate to Atlassian's Confluence.
RefactorDW is hosted at sourceforge.net (http://refactordw.sourceforge.net)
1) Preconditions
-------------------------
For running RefactorDW the following preconditions must be fulfilled:
- OS must be Linux
- Java 6 or higher must be installed on your system
- if you want to build RefactorDW: Ant and JUnit4 must be installed and available
2) Features
-------------------------
"RefactorDW" provides the following features:
- performs all operations on a temporary workspace copy preserving the original dokuwiki pages
- Article Link Normalization:
- transforms relative Dokuwiki article links into absolute links that contain the full name space path (e.g from [[myarticle]] to [[my:namespace:myarticle]])
- transforms relative Dokuwiki article links pointing to a chapter in same article into absolute links that contain the full name space path (e.g from [[#a chapter]] to [[my:namespace:myarticle#a chapter]])
- substitutes name space separator from '/' in article links by ':', which are more syntax compliant (also for older dokuwiki versions)
- Resolve naming conflicts
- resolves naming conflicts between articles (e.g. from [[my:namespace:start]] into [[my:namespace:my_namespace_start]]) (*)
- resolves naming conflicts between name spaces(*)
- resolves naming conflicts between name spaces and articles(*)
- Namespace relocation: moves a complete name space into another name space using a pre-configured mapping
3) Setup
-------------------------
a) Extract the RefactorDW release file into a directory of your choice
b)Adopt the configuration file config/refactordw_config.xml: the root directory must be set correctly to an existing directory where the original dokuwiki articles are located.
4) Executing
-------------------------
a) cd into the directory where RefactorDW has been extracted
b) Execute the following command line call in order to perform a Dokuwiki refactoring:
'java -Xmx<maxmemory> RefactorDW.jar'
c) The refactored results (articles) are put in the system's temporary directory (/tmp)
<maxmemory>: some operations like replacing strings in huge article content require much memory. If you encounter problems like 'OutOfMemoryExceptions' then increase the maximum amount of available memory (in megabytes) for the JVM. For example: 512 or 1024
5) Known Limitations
-------------------------
- Not all link syntax combinations are supported: dot-operators in Dokuwiki links are ignored (e.g. [[.:my:namespace]])
6) Licencing
-------------------------
RefactorDW is published under the MIT licence.
Annotations:
(*): Confluence does not accept non-unique article naming. When importing into confluence uwing UWC all name space will be transormed into articles (depending on UWC configuration).
Without re-factoring using RefactorDW those transormations would generate loads of naming conflicts leading to unnoticed overwritings of articles!