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.
- 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:
- TWiki Plugins - Easily install program enhancements using external plug-in modules. Developers can create plug-ins in Perl, with the TWiki Plugin API.
- TWikiTemplateSystem - New, more flexible template system.
- TWikiSkins - Overwrite template headers and footers; page content is unaffected.
- TWikiMetaData - New data format
- TWikiFormTemplate - Create multiple input forms per web; data is rendered in HTML tables.
- Rename/move/delete topics Individual pages can be managed through the browser. Deleted topics are stored in a common Trash web.
- Change passwords Change and reset passwords using forms.
- TOC (Table of Contents) -
%TOC%
variable generates a hierarchical table of contents from topic headings: <HI>...<H6>. Set depth.
- Arbitrary Text for WikiWord Links - Text formatting rules to generate automatic links from any combination of words and spaces.
- [[TWiki.FileAttachments][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
-
- Backup all existing TWiki directories (
bin
, pub
, data
, templates
)
-
- Unpack the zip file into some working directory:
mkdir -p ~/tmp/
cd ~/tmp
unzip ~/TWiki20001201.zip
Step 2: Upgrade TWiki document files
-
- Move the document files to your TWiki root (
twiki
):
mv ~/tmp/TWiki*.html $TWIKIROOT
mv ~/tmp/index.html $TWIKIROOT
mv ~/tmp/readme.txt $TWIKIROOT
mv ~/tmp/license.txt $TWIKIROOT
Step 3: Upgrade CGI scripts
-
- Rename your original
twiki/bin
directory: ( twiki/bin
)
mv $TWIKIROOT/bin $TWIKIROOT/bin.old
- Move the new scripts to your original
twiki/bin
location, i.e.
mv ~/tmp/bin $TWIKIROOT/bin
- 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:
diff -c $TWIKIROOT/bin.old/wikicfg.pm $TWIKIROOT/bin/wikicfg.pm | less
- Restore any additional scripts you might have from the old directory, ex:
mv $TWIKIROOT/bin.old/somescript $TWIKIROOT/bin/
- Test your TWiki installation if you can view topics.
-
- Pay attention to the file and directory permissions (security issue)
Step 4: Upgrade template files
-
- Rename your original
twiki/templates
directory: ( twiki/templates
)
mv $TWIKIROOT/templates $TWIKIROOT/templates.old
- Move the new templates to your original
twiki/templates
location:
mv ~/tmp/templates $TWIKIROOT/templates
- Customized templates and skins need to be upgraded to the 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 TextFormattingRules, but you have to escape unwanted ones. Also, remove empty lines unless you want a
=<p />
tag added.
- Added TWikiMetaData rendering.
- The Form Templates replace the TWikiCategoryTable:
- 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.
- __Merge the changes in your current template files into the new template files. To compare two files use
=diff -c $TWIKIROOT/templates.old/view.tmpl $TWIKIROOT/templates/view.tmpl | less=__
- For each web that has a custom
notedited.tmpl
template, create a WebTopicEditTemplate to conform with the new SelectableNewTopicTemplates feature. Retired notedited.tmpl
, notext.tmpl
and notwiki.tmpl
templates.
- Restore any additional template subdirectories of your TWiki webs you might have and merge the changes.
- Test your TWiki installation to see if you can view topics.
Step 5: Upgrade public files
-
- Move the new
twiki/pub/TWiki
directory to your installation: ( twiki/pub
)
mv ~/tmp/pub/TWiki $TWIKIROOT/pub/
- Move the new
twiki/pub/twikilogo*
image files to your installation:
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
-
- Move the new
twiki/data/TWiki
directory to your installation: ( twiki/data
)
mv ~/tmp/data/TWiki $TWIKIROOT/data/
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")
- Optionally move the new
twiki/data/Test
directory to your installation,
mv ~/tmp/data/Test $TWIKIROOT/data/
(Pay attention to the file permissions)
-
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*
.
-
TWikiPreferences
into TWiki.TWikiPreferences
.
- Merge your changes to the
WebPreferences
topics in all your webs into WebPreferences
- Modify the
WebPreferences
topics in all your webs to reflect the following:
-
WEBTOPICLIST
should use WebChanges
for "Changes"
, and WebIndex
for "Index"
:
| <a href="WebChanges">Changes</a>
| <a href="WebIndex">Index</a>
- In case you want to exclude a web from a
web="all"
search: Set this new preference
Set NOSEARCHALL = on
- 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.
- Change the
WebHome
topics in all your webs to reflect these changes:
- If you are using
.htaccess
, add the rename
script
* You may want to add [ALLOW|DENY][WEB|TOPIC]RENAME
in some places, like TWikiTWikiPreferences?, WebPreferences and TWikiUsers
General Format Changes
- Format changed of
%GMTIME{"..."}%
and %SERVERTIME{"..."}%
variables. Format is now "$hour:$min"
instead of "hour:min"
. More in TWikiVariables.
- ExtendingTableSyntax?: Enhanced table syntax might have unwanted side effect:
| *bold* |
cells, | center aligned |
and | right aligned |
cells, span multiple columns using | empty cells |||
. More in TextFormattingRules.
- Use
Net::SMTP
module instead of sendmail
if installed.
- Use
<verbatim> ... </verbatim>
tags instead of <pre> ... </pre>
tags where appropriate. More in TextFormattingRules.
- New variable
%STARTINCLUDE%
and %STOPINCLUDE%
variables to control what gets included of a topic. More in TWikiVariables.
- FileAttachment info is now stored as 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 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
-
- Upgrading requires extensive changes be made to topics in the TWiki web.
--
JohnTalintyre? - 18 Jul 2001
to top