Manual for "RefactorDW"
============================
http://www.digitalcure.org
RefactorDW is a tool based on Java technology that provides several capabilities for re-structuring and re-factoring
existing Dokuwiki article assets.
This enables the user to re-structure the name space layout of Dokuwiki (move, merge, rename, flatten)
and to resolve naming conflicts between articles or name spaces.
A typical use case for using RefactorDW is preparing the migration from Dokuwiki to Confluence.
The batch operations are defined by an XML configuration file.
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
- RAM: 1GB or more
- 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)
4.1 Command Line Interface
- - - - - - - - - - - - - -
In order to use an alternative XML configuration file rather than the default one use the command line interface:
-config <file> defines an alternative XML configuration file
-help print command line syntax usage
<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.
7) Setup for Development & Building
-----------------------------------
7.1) Eclipse
- Install Ivy (if building via Ant is required)
- Install IvyDE Plugin if building via Eclipse IDE is required: http://ant.apache.org/ivy/ivyde/
- Install Checkstyle Plugin
7.2) Sources
- Checkout Sources from
- https://refactordw.svn.sourceforge.net/svnroot/refactordw/trunk
- https://lunarcp.svn.sourceforge.net/svnroot/lunarcp/trunk/org.digitalcure.lunarcp.settings (for the checkstyle configuration)
7.3) Build Path
- Right-click on the Eclipse project -> Build Path -> Add Libraries -> IvyDE Managed Library
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!