(r14)TWikiUpgradeTo01Dec2001 < TWiki

Webs
Main
Sandbox
TWiki
You are here: FS > TWiki Web > TWikiUpgradeTo01Dec2001	r14 - 08 Sep 2001 - 23:03 - MikeMannix^?
View topic \| ~~EditAttach~~Printable
Start of topic | Skip to actions
%TOC%
%STARTINCLUDE%
---# TWiki Upgrade Guide

_Upgrade from TWiki 01-Dec-2000 to TWiki 01-Sep-2001 (previous to new full release)_

---++ Overview

The latest version of TWiki (01-Sep-2001) involves several major new features and numerous enhancements to the last full version (01-Dec-2001). The file system set-up is almost identical, but much of the underlying data structure and processes are new. With all the changes, the upgrade procedure is straightforward, and your existing page data is imported directly. 

---++ Upgrade Requirements

   * To upgrade from a 01-Dec-2000 standard installation to the new, next generation 01-Sep-2001 TWiki Production Release, follow the instructions below.

   * __NOTE:__ To upgrade from a *pre-01-Dec-2000* TWiki, start with   %TWIKIWEB%.TWikiUpgradeTo01Dec2000.

   * To upgrade from a Beta of the new release, or if you made custom modifications to the application, read through all new reference documentation, then use the procedure below as a guideline.  

---++ Major Changes from TWiki 01-Dec-2000

The 01 Sep 2001 release includes the following new features and enhancements:

   * *[[TWikiDocumentation#TWiki_Plugins][TWiki Plugins]]* - Easily install program enhancements using external plug-in modules. Developers can create plug-ins in Perl, with the [[TWikiPlugins#PluginAPI][TWiki Plugin API]].
      * *[[TWikiDocumentation#InterwikiPlugin][InterwikiPlugin]]* (preinstalled) - Link to external sites with text aliases, =SiteAlias:Page=; rules are defined in InterWikis. (Get more Plugins from the TWiki:Plugins web.) 
   * *[[TWikiDocumentation#TWiki_Template_System][TWikiTemplateSystem]]* - New, more flexible template system.
   * *[[TWikiDocumentation#TWiki_Skins][TWikiSkins]]* - Overwrite template headers and footers; page content is unaffected. 
   * *[[TWikiDocumentation#TWiki_Meta_Data][TWikiMetaData]]* - New data format 
   * *[[TWikiDocumentation#TWiki_Form_Template][TWikiFormTemplate]]* - Create multiple input forms per web; data is rendered in HTML tables.
   * *[[TWikiDocumentation#Managing_Topics][Rename/move/delete topics]]* Individual pages can be managed  through the browser. Deleted topics are stored in a common Trash web.
   * *[[TWikiDocumentation#Changing_Passwords][Change passwords]]* Change and reset passwords using forms.
   * *TOC (Table of Contents)* - =%<nop>TOC%= variable generates a hierarchical table of contents from topic headings: &lt;HI&gt;...&lt;H6&gt;. Set depth.
   * *[[%TWIKIWEB%.TWikiVariables][Arbitrary Text for <nop>WikiWord Links]]* - Text formatting rules to generate automatic links from any combination of words and spaces.
   * *[[%TWIKIWEB%.FileAttachment][Attachments Under Revision Control]]* Changes to files attached to topics - - are now tracked under revision control (RCS).
   * *ConvertToXHTML10* - Templates and HTML page rendering are in XHTML 1.0 as far as possible without breaking HTML 3.2 compliance.
   * *HierarchicalNavigation* uses new Meta Data variables to link hierarchically, for example, as in Yahoo! and other search sites. 

The TWiki directory structure remains the same, with one exception, the new =lib/TWiki/Plugins= directory tree to for the main configuration file, library, internal modules and the new Plugin modules. Pre-existing files were formerly in =bin=.

---++ Standard Upgrade Procedure

Follow this step-by-step guide to upgrade the 01 Dec 2000 version to the 01 Sep 2001 release, and import your original page data:

---+++ Step 1: Backup & Unpack

      1. Backup all existing TWiki directories ( =bin=, =pub=, =data=, =templates= )

      1. Unpack the zip file into some working directory:
     <br> =mkdir -p ~/tmp/=
     <br> =cd ~/tmp=
     <br> =unzip ~/TWiki20001201.zip=

---+++ Step 2: Upgrade TWiki document files 

      1. Move the document files to your TWiki root ( =twiki= ):
        <br> =mv ~/tmp/TWiki*.html $TWIKIROOT=
        <br> =mv ~/tmp/index.html $TWIKIROOT=
        <br> =mv ~/tmp/readme.txt $TWIKIROOT=
        <br> =mv ~/tmp/license.txt $TWIKIROOT=

---+++ Step 3: Upgrade CGI scripts

      1. Rename your original =twiki/bin= directory: ( =twiki/bin= )
        <br> =mv $TWIKIROOT/bin $TWIKIROOT/bin.old=
      1. Move the new scripts to your original =twiki/bin= location, i.e.
        <br> =mv ~/tmp/bin $TWIKIROOT/bin=
      1. Merge the changes in your current =wikicfg.pm= into the new =wikicfg.pm=. We suggest using =diff -c= to compare the two files if you have made heavy changes to the file:
        <br> =diff -c $TWIKIROOT/bin.old/wikicfg.pm $TWIKIROOT/bin/wikicfg.pm | less=
      1. Restore any additional scripts you might have from the old directory, ex:
        <br> =mv $TWIKIROOT/bin.old/somescript $TWIKIROOT/bin/=
      1. Test your TWiki installation if you can view topics.
        
      * Pay attention to the file and directory permissions (security issue)

---+++ Step 4: Upgrade template files 

      1. Rename your original =twiki/templates= directory: ( =twiki/templates= )
        <br> =mv $TWIKIROOT/templates $TWIKIROOT/templates.old=
      1. Move the new templates to your original =twiki/templates= location:
        <br> =mv ~/tmp/templates $TWIKIROOT/templates=
      1. Customized templates and skins need to be upgraded to the [[TWikiDocumentation#TWiki_Template_System][new template format]]. The safest way is to use the new templates as a base and to merge your changes back. Changes in new templates:
         * Changed format from HTML to XHTML.
         * Templates are now rendered by TWiki. You can use all [[TWikiDocumentation#TextFormattingRules][TextFormattingRules]], but you have to escape unwanted ones. Also, remove empty lines unless you want a ==&lt;p /&gt;= tag added.
         * Added [[TWikiDocumentation#TWiki_Meta_Data][TWikiMetaData rendering]]. 
      1. The Form Templates replace the <nop>TWikiCategoryTable:
         * [[TWikiDocumentation#FormsVsCategoryTables][Create a replacement Form Template]] based on =twikicatitems.tmpl= in each web that used a Category Table.
         * Searches need to be adjusted to deal with format change - if all topics are upgrades, a more specific search can be done.
      1. __Merge the changes in your current template files into the new template files. To compare two files use
        <br> =diff -c $TWIKIROOT/templates.old/view.tmpl $TWIKIROOT/templates/view.tmpl | less=__
      1. For each web that has a custom ==notedited.tmpl== template, create a WebTopicEditTemplate to conform with the new [[TWikiDocumentation#SelectableNewTopicTemplates][SelectableNewTopicTemplates]] feature. Retired =notedited.tmpl=, =notext.tmpl= and =notwiki.tmpl= templates.
      1. Restore any additional template subdirectories of your TWiki webs you might have and merge the changes.
      1. Test your TWiki installation to see if you can view topics.

---+++ Step 5: Upgrade public files

      1. Move the new =twiki/pub/TWiki= directory to your installation: ( =twiki/pub= )
        <br> =mv ~/tmp/pub/TWiki $TWIKIROOT/pub/=
      1. Move the new =twiki/pub/twikilogo*= image files to your installation:
        <br> =mv ~/tmp/pub/twikilogo* $TWIKIROOT/pub=
        
      * Pay attention to the file permissions of the =TWiki= directory and its subdirectory and files. The files must be writable by the CGI scripts (usually user "nobody").

---+++ Step 6: Upgrade data files 

      1. Move the new =twiki/data/TWiki= directory to your installation: ( =twiki/data= )
        <br> =mv ~/tmp/data/TWiki $TWIKIROOT/data/=
        <br> Pay attention to the file permissions of the =TWiki= directory and its files. The files must be writable by the cgi-scripts (usually user "nobody")
      1. Optionally move the new =twiki/data/Test= directory to your installation,
        <br> =mv ~/tmp/data/Test $TWIKIROOT/data/=
        <br> (Pay attention to the file permissions)
      1. =TWikiRegistration= moved from TWiki.Main to TWiki.TWiki. In case you customized =TWikiRegistration= , merge your changes back into =TWiki.TWikiRegistration= , then delete =$TWIKIROOT/data/Main/TWikiRegistration*=.
      1. =TWikiPreferences= into =TWiki.TWikiPreferences=.
      1. Merge your changes to the =WebPreferences= topics in all your webs into =WebPreferences=
      1. Modify the =WebPreferences= topics in all your webs to reflect the following:
         * =WEBTOPICLIST= should use =WebChanges= for ="Changes"=, and =WebIndex= for ="Index"=:
           <br> =| &lt;a href="WebChanges"&gt;Changes&lt;/a&gt;=
           <br> =| &lt;a href="WebIndex"&gt;Index&lt;/a&gt;=
         * In case you want to exclude a web from a =web="all"= search: Set this new preference
           <br> =Set NOSEARCHALL = on=
      1. The =WebSearch= topic has considerable changes. Copy the one from =TWiki.TWiki= into all webs, or merge them if you made changes. To copy, do an edit-copy-edit-paste operation.
      1. __Change the =WebHome= topics in all your webs to reflect these changes:__
      1. If you are using ==.htaccess==, add the =rename= script
        * You may want to add =[ALLOW|DENY][WEB|TOPIC]RENAME= in some places, like  %TWIKIWEB%.TWikiPreferences, WebPreferences and %MAINWEB%.TWikiUsers
        
---+++ General Format Changes

   * Format changed of ==%<nop>GMTIME{"..."}%== and ==%<nop>SERVERTIME{"..."}%== variables. Format is now =="$hour:$min"== instead of =="hour:min"==. More in %TWIKIWEB%.TWikiVariables.

   * [[%TWIKIWEB%.TWikiVariables][ExtendingTableSyntax]]: Enhanced table syntax might have unwanted side effect: ==| <nop>*bold*<nop> |== cells, ==|  center aligned  |== and ==|   right aligned |== cells, span multiple columns using ==| empty cells |||==. More in %TWIKIWEB%.TextFormattingRules.

   * Use ==Net::SMTP== module instead of ==sendmail== if installed. 

   * Use ==&lt;verbatim&gt; ... &lt;/verbatim&gt;== tags instead of ==&lt;pre&gt; ... &lt;/pre&gt;== tags where appropriate. More in %TWIKIWEB%.TextFormattingRules.

   * New variable ==%<nop>STARTINCLUDE%== and ==%<nop>STOPINCLUDE%== variables to control what gets included of a topic. More in %TWIKIWEB%.TWikiVariables.
   
   * FileAttachment info is now stored as [[TWikiDocumentation#TWiki_Meta_Data][TWiki Meta Data]].
      * Upgrading of imported pagess is done automatically after first edit, on save. "In memory" upgrade is done on topic view.
      * Attachments are now under revision control: =$attachAsciiPath= in =TWiki.cfg= defines which file types are stored in ASCII, otherwise, binary format is used. This means that the RCS version used should support binary files.

   * Handling for topic-specific templates like =edit.new.tmpl= has been removed and replaced by template topics in the new [[TWikiDocumentation#TWiki_Template_System][TWiki Template System]] )

   * A new file =warning.txt= file can appear in the =data= directory. It may contain diagnostic info identifying problems that need fixing. This file could get fairly large if you have a lot of problems your site - you can delete it at any time.
   
---++ Known Upgrade Issues

      * Check http://TWiki.org/cgi-bin/view/Codev/KnownIssuesOfTWiki01Sep2001 for known issues of TWiki 01 Sep 2001 (production release)
      
      * __Upgrading requires extensive changes be made to topics in the TWiki web.__

-- Main.JohnTalintyre - 18 Jul 2001 <br>
End of topic
Skip to actions | Back to top
Copyright © by the contributing authors. All material on this collaboration platform is the property of the contributing authors.
Ideas, requests, problems regarding FS? Send feedback