1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
|
%TOC% %STARTINCLUDE%
## <a name="TWiki_Upgrade_Guide"> TWiki Upgrade Guide </a>
_Upgrading from the 01-Dec-2000 release to the new TWiki 01-Sep-2001_
### <a name="Overview"> Overview </a>
The latest version of TWiki (01-Sep-2001) involves several major new features and numerous enhancements of 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.
### <a name="Upgrade_Requirements"> Upgrade Requirements </a>
* 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've made custom modifications, read through the documentation and use the procedure below as a guideline.
### <a name="Major_Changes_from_TWiki_01_Dec_"> Major Changes from TWiki 01-Dec-2000 </a>
The 01 Sep 2001 release includes the following new features and enhancements:
* **[[TWikiPlugins]]** - Easily install program enhancements using external plug-in modules. Developers can create plug-ins in Perl, with the [[TWikiPlugins]].
* **[[InterwikiPlugin]]** (preinstalled) - Link to external sites with text aliases, `SiteAlias:Page`; rules are defined in [[InterWikis]]. (Get more Plugins from the TWiki:Plugins web.)
* **[[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.
* **[[ManagingTopics]]** Individual pages can be managed through the browser. Deleted topics are stored in a common Trash web.
* **[[TWikiUserAuthentication]]** Change and reset passwords using forms
* **TOC (Table of Contents)** - <code>%TOC%</code> variable generates a hierarchical table of contents from topic headings: <HI>...<H6>. Set depth.
* **ArbitraryTextForWikiWordLinks** - Text formatting rules to form links from any combination of words and spaces.
* **AttachmentsUnderRevisionControl** Changes to files attached to topics - [[FileAttachments]] - 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**
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`.
### <a name="Standard_Upgrade_Procedure"> Standard Upgrade Procedure </a>
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:
#### <a name="Step_1_Backup_amp_Unpack"> Step 1: Backup & Unpack </a>
1. 1. Backup all existing TWiki directories ( `bin`, `pub`, `data`, `templates` )
1. 1. Unpack the zip file into some working directory: <br />`mkdir -p ~/tmp/`<br />`cd ~/tmp`<br />`unzip ~/TWiki20001201.zip`
#### <a name="Step_2_Upgrade_TWiki_document_fi"> Step 2: Upgrade TWiki document files </a>
1. 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`
#### <a name="Step_3_Upgrade_CGI_scripts"> </a> Step 3: Upgrade CGI scripts
1. 1. Rename your original `twiki/bin` directory: ( `twiki/bin` ) <br />`mv $TWIKIROOT/bin $TWIKIROOT/bin.old`
2. Move the new scripts to your original `twiki/bin` location, i.e. <br />`mv ~/tmp/bin $TWIKIROOT/bin`
3. 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`
4. Restore any additional scripts you might have from the old directory, ex: <br />`mv $TWIKIROOT/bin.old/somescript $TWIKIROOT/bin/`
5. Test your TWiki installation if you can view topics.
* * Pay attention to the file and directory permissions (security issue)
#### <a name="Step_4_Upgrade_template_files"> Step 4: Upgrade template files </a>
1. 1. Rename your original `twiki/templates` directory: ( `twiki/templates` ) <br />`mv $TWIKIROOT/templates $TWIKIROOT/templates.old`
2. Move the new templates to your original `twiki/templates` location: <br />`mv ~/tmp/templates $TWIKIROOT/templates`
3. \_\_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=\_\_
4. Restore any additional template subdirectories of your TWiki webs you might have and merge the changes.
5. Test your TWiki installation to see if you can view topics.
#### <a name="Step_5_Upgrade_public_files"> Step 5: Upgrade public files </a>
1. 1. Move the new `twiki/pub/TWiki` directory to your installation: ( `twiki/pub` ) <br />`mv ~/tmp/pub/TWiki $TWIKIROOT/pub/`
2. 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").
#### <a name="Step_6_Upgrade_data_files"> Step 6: Upgrade data files </a>
1. 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")
2. 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)
3. `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*`.
4. `TWikiPreferences` into `TWiki.TWikiPreferences`.
5. Merge your changes to the `WebPreferences` topics in all your webs into `WebPreferences`
6. Modify the `WebPreferences` topics in all your webs to reflect the following:
* `WEBTOPICLIST` should use `WebChanges` for `"Changes"`, and `WebIndex` for `"Index"`: <br />`| <a href="WebChanges">Changes</a>`<br />`| <a href="WebIndex">Index</a>`
* In case you want to exclude a web from a `web="all"` search: Set this new preference <br />`Set NOSEARCHALL = on`
7. 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.
8. **_Change the `WebHome` topics in all your webs to reflect these changes:_**
### <a name="Known_Upgrade_Issues"> Known Upgrade Issues </a>
* * Check <http://TWiki.org/cgi-bin/view/Codev/KnownIssuesOfTWiki01Sep2001> for known issues of TWiki 01 Sep 2001 (production release)
|
