/ 
SilkiX-Converter-Kwiki-0.03
River stage zero No dependents
/ SilkiX::Converter::Kwiki

NAME

SilkiX::Converter::Kwiki - Convert a Kwiki wiki to a Silki wiki

VERSION

version 0.03

SYNOPSIS

kwiki2silki --wiki           'Silki Wiki Title'   \
            --kwiki-root     /path/to/kwiki       \
            --user-map-file  /path/to/map.json    \
            --default-user   DefaultNameFromKwiki \
            --fast

SILKIX_CONVERTER=MyCustomConversionSubclass \
  kwiki2silki --wiki           'Silki Wiki Title'   \
              --kwiki-root     /path/to/kwiki       \
              --user-map-file  /path/to/map.json    \
              --default-user   DefaultNameFromKwiki

DESCRIPTION

This module lets you convert a Kwiki wiki into a Silki wiki. The primary interface is via the kwiki2silki script that ships with this distribution.

If you define a SILKIX_CONVERTER environment variable, then this class will be used to do the conversion. This lets you create a custom subclass, which can be useful, especially when it comes to default values for users and for mapping page titles from Kwiki to Silki.

WARNINGS

If you pass the --fast option, the converter disables some database triggers in order to speed things up, and restores them at the end of the conversion. It attempts to restore them if the process fails mid-stream, but this is software, and software has bugs.

If you have other wikis which are in use, make sure to backup your database with pg_dump. Also, shut down the web UI during the conversion, or else other wikis could end up corrupted because of the missing triggers.

The converter assumes that the wiki you're writing to is effectively empty. Don't try to convert into an already-in-use wiki!

Basically, this software is rough, and could mess you up. Be careful.

KWIKI PLUGINS

This module assumes that your Kwiki install has certain plugins. It assumes that your Kwiki install has one of the archive plugins installed, though it doesn't matter which one.

You also will need the Kwiki::Attachments module installed. This may fail tests, but just force it (sigh). However, if your kwiki install does not load the attachments plugin, that's ok. If it does, then this converter will convert attachments too.

USER MAP FILE

By default, the converter does a dumb mapping of kwiki usernames to Silki users. The email address is $kwiki_user@localhost.localdomain.

If you want to make useful accounts for users, you can create a user map JSON file.

This should be a JSON object (aka hash) where the keys are Kwiki usernames. The values can either be an object describing the user for Silki, or another key name. If it is another key name, then the converter follows the references until it finds an object or ten links have been followed, at which point it blows up.

The Silki user object in the user map can have the following keys:

  • email_address

  • password

    Defaults to "change me".

  • display_name

    The name used by Silki to display the user. This can be empty.

  • time_zone

    Must be an Olson time zone. Defaults to "America/New_York".

  • is_disabled

    A boolean which defaults to false.

CONVERTING TITLES

By default, titles are converted by splitting StudlyCaps words apart, so "RandomKwikiPage" becomes "Random Kwiki Page".

The one exception is that the Kwiki "HomePage" becomes the Silki "Front Page".

You can use a converter subclass to add more intelligence to this process.

Also, you'll need to manually delete your wiki's front page (for now).

DUMPING TITLES AND USERS

The kwiki2silki script can dump all titles and users from your kwiki install:

kwiki2silki --wiki           'Silki Wiki Title'   \
            --kwiki-root     /path/to/kwiki       \
            --dump-page-titles                    \
            --dump-usernames

This is very handy in helping you come up with a user map.

AUTHOR

Dave Rolsky <autarch@urth.org>

COPYRIGHT AND LICENSE

This software is Copyright (c) 2010 by Dave Rolsky.

This is free software, licensed under:

The Artistic License 2.0