This page gives suggestions for upgrading an existing PmWiki 1.x installation to use PmWiki 2.0. In this page we assume that a site administrator already has a site running using PmWiki version 1.x or earlier in a somewhat standard configuration, and wants to upgrade to the 2.0 software.
As always, questions and requests for assistance can be posed to pmwiki-users?. Errors or problems with the methods below can be corrected here, or posted to the PmWiki Issue Tracking System.
Because of the substantial redesign of PmWiki for 2.0, converting an existing site to 2.0 is likely to cause a wiki administrator a fair amount of apprehension. The approach given here allows the administrator to install, configure, and test PmWiki 2.0 on an existing set of pages without risking an existing 1.x installation.
Step 1: Download and install PmWiki 2.0 into a new directory away from the existing 1.x installation.
Step 2: Briefly test the PmWiki 2.0 installation and make sure it is working properly -- i.e., edit and save a couple of pages.
Step 3: Add the following lines to the local/config.php file in the 2.0 installation, replacing "/path/to/pmwiki1/wiki.d" below with the location of your PmWiki 1.x installation's wiki.d/ directory on disk.
include_once("$FarmD/scripts/compat1x.php");
$WikiLibDirs = array(&$WikiDir,
new PageStore1x("/path/to/pmwiki1/wiki.d/\$FullName"),
new PageStore("$FarmD/wikilib.d/\$FullName"));
For example, my 2.0 test conversion uses:
include_once("$FarmD/scripts/compat1x.php");
$WikiLibDirs = array(&$WikiDir,
new PageStore1x("/home/pmichaud/pmwiki/wiki.d/\$FullName"),
new PageStore("$FarmD/wikilib.d/\$FullName"));
Before running the above configuration, remove from the PmWiki2? wiki.d directory all pages that you have saved in the preliminary test, especially homepage.
Step 4: After making the above change, all of your existing pages should appear in the new 2.0 installation. Furthermore, if you "edit page" on any of the existing pages, you should see that any PmWiki 1.x markups (links, etc.) have been converted to the new markup syntax.
Any pages edited/saved by the 2.0 wiki installation are kept separate from the pages in the previous installation. Thus you can safely experiment with editing and changing pages in the new site without affecting the existing 1.x site.
Step 5: Once you see that your existing pages are available in the 2.0 installation, you can then begin going through the remaining initial setup tasks for the 2.0 site to enable any local customizations you may want for your site. Many local customizations (e.g. page layout templates) remain the same between 1.x and 2.0, others such as custom markup or cookbook recipes need to be converted to 2.0 as well.
Step 6: Continue configuring the new installation just as if you were setting up a new PmWiki site. If you find PmWiki 1.x markups that aren't converted or convert incorrectly, be sure to enter a new PITS issue so that we can improve the conversion script.
Once you're comfortable that the PmWiki 2.0 site will meet your needs, you can then discontinue the 1.x site and just start using the 2.0 site. If you decide that 2.0 isn't for you, then the 1.x site is still intact and can continue to be used.