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
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
|
%TOC% %STARTINCLUDE%
# <a name="TWiki_Upgrade_Guide"> TWiki Upgrade Guide </a>
_Upgrade from TWiki 01-Dec-2000 to TWiki 01-Sep-2001 (previous to new full release)_
## <a name="Overview"> Overview </a>
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.
## <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 made custom modifications to the application, read through all new reference documentation, then 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:
* **[[TWikiDocumentation]]** - Easily install program enhancements using external plug-in modules. Developers can create plug-ins in Perl, with the [[TWikiPlugins]].
* [[TWikiDocumentation]] (preinstalled) - Link to external sites with text aliases, `SiteAlias:Page`; rules are defined in [[InterWikis]]. (Get more Plugins from the TWiki:Plugins web.)
* **[[TWikiDocumentation]]** - New, more flexible template system.
* **[[TWikiDocumentation]]** - Overwrite template headers and footers; page content is unaffected.
* **[[TWikiDocumentation]]** - New data format
* **[[TWikiDocumentation]]** - Create multiple input forms per web; data is rendered in HTML tables.
* **[[TWikiDocumentation]]** Individual pages can be managed through the browser. Deleted topics are stored in a common Trash web.
* **[[TWikiDocumentation]]** Change and reset passwords using forms.
* **[[TWIKIWEBTWikiVariables]]** - <code>%TOC%</code> variable generates a hierarchical table of contents from topic headings: <HI>...<H6>. Set depth.
* **[[TWIKIWEBTWikiVariables]]** - Text formatting rules to generate automatic links from any combination of words and spaces.
* **[[TWIKIWEBFileAttachment]]** Changes made to files attached to topics are now saved under revision control (RCS).
* **Convert to XHTML** - 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.
* **SuperAdministrator Group** allows you to give one user group - by default, TWikiAdminGroup - superpowers: the ability to overwrite locked topics from the browser interface. (This gets around a potential problem where mistyping topic access definition could result in locking everyone out.)
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 from the 01-Dec-2000 TWiki to the 01-Sep-2001 release, importing your original page data and related files:
### <a name="Pre_Upgrade_Preparation"> Pre-Upgrade Preparation </a>
Two major areas of TWiki functionality - [[TWikiDocumentation]] and [[TWikiDocumentation]] (input forms associated with a topic)- are entirely different in the new TWiki. Therefore, if you've customized your templates or use Category Tables, you should read those sections _before_ starting your upgrade. That way, converting old templates and pages to new will be flow along smoothly!
### <a name="Step_1_Backup_amp_Unpack"> Step 1: Backup & Unpack </a>
1. 1. Move all existing TWiki directories ( `bin`, `pub`, `data`, `templates` ) to a temporary directory (it's a good idea to do a full back-up first): <br />`mkdir -p ~/tmp/`<br />`mv $TWIKIROOT/* ~/tmp/`
2. Unpack the zip file into your newly empty working directory: <br />`cd $TWIKIROOT`<br />`unzip ~/TWiki20010901.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. If necessary, change the script names to include the required extension, ex: `.cgi`
2. Restore any additional scripts you might have from the `tmp` directory, ex: <br />`mv ~/tmp/bin/somescript $TWIKIROOT/bin/`
3. Set permissions, ex: <br />`chmod 755 *.cgi`
4. Restore any additional scripts you might have from the `tmp` directory, ex: <br />`mv ~/tmp/bin/somescript $TWIKIROOT/bin/`
5. Test your TWiki installation to see if you can view topics.
* * Pay attention to the file and directory permissions (security issue)
### <a name="Step_4_Set_configurations_in_TWi"> Step 4: Set configurations in `TWiki.cfg` </a>
1. 1. Customize the new `lib/TWiki.cfg` configuration file, which replaces the `wikicfg.pm` file. New settings to watch for:
* SuperAdminCanConfig
*
2. Test your TWiki installation to see if you can view topics.
3. Test the new [[TWikiDocumentation]] by checking the Plugins settings in [[TWikiPreferences]].
* The <code>EmptyPlugin</code>, <code>DefaultPlugin</code>, and <code>InterwikiPlugin</code> should be preinstalled. To check the %TWIKIWEB%.InterwikiPlugin, go to its page.
* * Pay attention to the file and directory permissions (security issue)
### <a name="Step_5_Upgrade_template_files"> Step 5: Upgrade template files </a>
1. 1. Customized templates and skins need to be upgraded to the new [[TWikiDocumentation]]. This isn't difficult, but you have be familiar with the new template set-up before starting the conversion. The safest way is to use the new templates as a base and to merge your changes back. Changes in new templates:
* Templates are now rendered by TWiki. You can use all [[TWikiDocumentation]], but you have to escape unwanted ones. Also, remove empty lines unless you want a `=<p />` tag added.
* Added [[TWikiDocumentation]].
2. Form Templates replace the TWikiCategoryTables:
* [[TWikiDocumentation]] 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.
3. For each web that has a custom <code>**notedited.tmpl**</code> template, create a [[WebTopicEditTemplate]] to conform with the new [[TWikiDocumentation]] feature. Retired `notedited.tmpl`, `notext.tmpl` and `notwiki.tmpl` templates.
4. Test your TWiki installation to see if you can view topics.
### <a name="Step_6_Upgrade_public_files"> Step 6: Upgrade public files </a>
1. 1. Move your own public data files and sub-directories from the original `pub` directory to the new installation: ( `$TWIKIROOT/pub` ) <br />`mv ~/tmp/pub/TWiki/somefiles.ext $TWIKIROOT/pub/`<br />`mv ~/tmp/pub/TWiki/somedirectory $TWIKIROOT/pub/`
### <a name="Step_7_Upgrade_data_files"> Step 7: Upgrade data files </a>
1. 1. Move the `tmp/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. `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*`.
3. `TWikiPreferences` into `TWiki.TWikiPreferences`.
4. Merge your changes to the `WebPreferences` topics in all your webs into `WebPreferences`
5. Modify the `WebPreferences` topics in all your webs to reflect the following:
*
* In case you want to exclude a web from a `web="all"` search: Set this new preference <br />`Set NOSEARCHALL = on`
6. 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.
7. **_Change the `WebHome` topics in all your webs to reflect these changes:_**
8. If you are using <code>**.htaccess**</code>, add the `rename` script \* You may want to add `[ALLOW|DENY][WEB|TOPIC]RENAME` in some places, like %TWIKIWEB%.TWikiPreferences, [[WebPreferences]] and %MAINWEB%.TWikiUsers
### <a name="General_Format_Changes"> General Format Changes </a>
* Format changed of <code>**%GMTIME\{"..."\}%**</code> and <code>**%SERVERTIME\{"..."\}%**</code> variables. Format is now <code>**"$hour:$min"**</code> instead of <code>**"hour:min"**</code>. More in %TWIKIWEB%.TWikiVariables.
* [[TWIKIWEBTWikiVariables]]: Enhanced table syntax might have unwanted side effect: <code>**| \*bold\* |**</code> cells, <code>**| center aligned |**</code> and <code>**| right aligned |**</code> cells, span multiple columns using <code>**| empty cells |||**</code>. More in %TWIKIWEB%.TextFormattingRules.
* Use <code>**Net::SMTP**</code> module instead of <code>**sendmail**</code> if installed.
* Use <code>**<verbatim> ... </verbatim>**</code> tags instead of <code>**<pre> ... </pre>**</code> tags where appropriate. More in %TWIKIWEB%.TextFormattingRules.
* New variable <code>**%STARTINCLUDE%**</code> and <code>**%STOPINCLUDE%**</code> variables to control what gets included of a topic. More in %TWIKIWEB%.TWikiVariables.
* [[FileAttachment]] info is now stored as [[TWikiDocumentation]].
* 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]] )
* 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.
## <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)
* * **_Upgrading requires extensive changes be made to topics in the TWiki web._**
-- [[Main/JohnTalintyre]] - 18 Jul 2001 <br />
|
