"RefactorDW" Manual
============================
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:
- RAM: 1GB or more
- Java 6 or higher must be installed on your system
- if you want to build RefactorDW: Ant, Ivy 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 and media files.
- 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).
- Substitutes the braces of all links to media files from [[-braces to
{{-braces.
- Resolve naming conflicts:
- Resolves naming conflicts between articles (e.g. from [[my:namespace:start]]
into [[my:namespace:my_namespace_start]]) (*).
- Resolves naming conflicts between media files (e.g. from
[[my:namespace:info.pdf]] into [[my:namespace:my_namespace_info.pdf]]) (*).
- Resolves naming conflicts between name spaces (*).
- Resolves naming conflicts between name spaces and articles (*).
- Name space 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 pages root
and the media directories have be set correctly to existing directories where
the original DokuWiki articles and media files are located.
4) Execution
-------------------------
a) Change current directory to the directory where RefactorDW has been extracted.
b) Execute the following command line call in order to perform a DokuWiki refactoring:
'java -Xmx<maxmemory> -jar RefactorDW.jar'
<maxmemory>: Some operations like replacing strings in huge articles require
a lot of memory. If you encounter problems like 'OutOfMemoryExceptions', then
increase the maximum amount of available memory for the JVM, e.g. "512m" or
"1024m".
c) The refactored results (articles and media files) are stored in the temporary
directory of the operating system, e.g. "/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
5) Known Limitations
-------------------------
- Not all link syntax combinations are supported and therefore are ignored:
- double-dot-operators in DokuWiki links are ignored, e.g. [[..:my:namespace]]
6) Licensing
-------------------------
RefactorDW is published under the MIT license.
7) Setup for Development & Building
-----------------------------------
7.1) Eclipse
- Install Ivy (if building via Ant is required)
- Install IvyDE plug-in if building via Eclipse IDE is required: http://ant.apache.org/ivy/ivyde/
- Install Checkstyle plug-in
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 using UWC all name space will be transformed into articles (depending
on UWC configuration). Without re-factoring using RefactorDW those
transformations would generate loads of naming conflicts leading to unnoticed
overwriting of articles!