version=pmwiki-2.2.0-beta68 ordered=1 urlencoded=1
agent=Mozilla/5.0 (Windows; U; Windows NT 5.1; en-GB; rv:1.9.0.1) Gecko/2008070208 Firefox/3.0.1
author=simon
charset=ISO-8859-1
csum=not on trail
host=202.37.32.2
name=PmWiki.UpgradingFromPmWiki1
rev=34
targets=PmWiki.WikiAdministrator,PmWiki.Upgrades,PmWiki.MailingLists,PmWiki.Installation,PmWiki.InitialSetupTasks,PmWiki.LocalCustomizations,PmWiki.CustomMarkup,PmWiki.WikiWord
text=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 [[(wiki) 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.%0a%0a->'''Important note:''' The normal PmWiki [[upgrade(s)]] procedure (i.e., copy the new software over the existing one) won't work for moving from 1.x to 2.0.  Either start over with a new installation, or use some of the conversion scenarios listed below.%0a%0aAs always, questions and requests for assistance can be posed to [[Mailing lists | pmwiki-users]].  Errors or problems with the methods below can be corrected here, or posted to the [[PITS:PITS |PmWiki Issue Tracking System]].%0a%0a!!!Method 1: Test conversion%0a%0aBecause 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.%0a%0a'''Step 0:'''  It's always a very good idea to back up your existing PmWiki 1.x installation before doing anything else -- especially save the files in the ''local/'' and ''wiki.d/'' directories.%0a%0a'''Step 1:'''  [[Install(ation)]] PmWiki 2.0 into a new directory away from the existing 1.x installation.%0a%0a'''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.  Then, remove the pages you created (you can just remove the files from PmWiki 2.0's ''wiki.d/'' directory, or remove the ''wiki.d/'' directory altogether).%0a%0a'''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.%0a    [=%0a    include_once("$FarmD/scripts/compat1x.php");%0a    UseV1WikiD("/path/to/pmwiki1/wiki.d");%0a    =]%0aFor example, my 2.0 test conversion uses:%0a    [=%0a    include_once("$FarmD/scripts/compat1x.php");%0a    UseV1WikiD("/home/pmichaud/pmwiki/wiki.d");%0a    =]%0a'''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.%0a%0aAny 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. %0a%0a'''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:Cookbook |cookbook recipes]] need to be converted to 2.0 as well.  %0a%0a'''Note:''' [[WikiWord]] links are disabled by default since Pmwiki version 2.1 beta2. So you may either enable WikiWord links by setting [@$LinkWikiWords = 1;@] in config.php, or convert your existing WikiWord links manually to bracketed links. To find those WikiWord links easier you can highlight them by setting in config.php%0a%0a       [=$HTMLStylesFmt['wikiword'] = "%0a       span.wikiword { background:yellow; }%0a       ";=] %0a%0a'''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 [[PITS:NewIssue |new PITS issue]] so that we can improve the conversion script.%0a%0a'''Step 7:'''  If you're comfortable with the conversion and want to go ahead and convert all of the 1.x pages into 2.0 format, change the [@UseV1WikiD(...)@] call in ''local/config.php'' above to [@ConvertV1WikiD(...)@] instead, as in:%0a    [=%0a    include_once("$FarmD/scripts/compat1x.php");%0a    ConvertV1WikiD("/path/to/pmwiki1/wiki.d");%0a    =]%0aRunning the pmwiki.php script will then bring up some forms to allow you to bulk migrate some or all of your 1.x pages to 2.0 format.  After you've converted pages, you can then just eliminate these two lines from the configuration and your PmWiki 2.0 site will be running standalone.%0a%0aIf you have local customisations that require you to specify $Compat1x['/match/'] = 'replace'; entries so they are correctly converted, make sure these are defined ''before'' the call to ConvertV1WikiD.%0a%0aNote that there's nothing that requires you to convert all of the pages or get rid of the 1.x ''wiki.d/'' directory -- PmWiki works just fine with it in place.  And it's good to have a backup.%0a%0a'''Step 8:''' 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.  Or, if you decide that 2.0 isn't for you, then the 1.x site is still intact and can continue to be used.%0a%0a'''Step 9:''' If your previous site had an ''uploads/'' directory, you'll probably want to copy it or move it into the new location.%0a
time=1220229688