diff options
Diffstat (limited to 'TWiki/TWikiUpgradeGuide.mdwn')
| -rw-r--r-- | TWiki/TWikiUpgradeGuide.mdwn | 86 |
1 files changed, 46 insertions, 40 deletions
diff --git a/TWiki/TWikiUpgradeGuide.mdwn b/TWiki/TWikiUpgradeGuide.mdwn index 111ec342..10438183 100644 --- a/TWiki/TWikiUpgradeGuide.mdwn +++ b/TWiki/TWikiUpgradeGuide.mdwn @@ -21,30 +21,34 @@ The latest version of TWiki (01-Sep-2001) involves several major new features an 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]] (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. -* **TOC (Table of Contents)** - <code>%TOC%</code> variable generates a hierarchical table of contents from topic headings: <HI>...<H6>. Set depth. +* **[[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 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. +* **[[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 the 01 Dec 2000 version to the 01 Sep 2001 release, and import your original page data: +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="Step_1_Backup_amp_Unpack"> Step 1: Backup & Unpack </a> +### <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! -1. 1. Backup all existing TWiki directories ( `bin`, `pub`, `data`, `templates` ) +### <a name="Step_1_Backup_amp_Unpack"> Step 1: Backup & Unpack </a> -1. 1. Unpack the zip file into some working directory: <br />`mkdir -p ~/tmp/`<br />`cd ~/tmp`<br />`unzip ~/TWiki20001201.zip` +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> @@ -52,50 +56,52 @@ Follow this step-by-step guide to upgrade the 01 Dec 2000 version to the 01 Sep ### <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. +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_4_Upgrade_template_files"> Step 4: Upgrade template files </a> +### <a name="Step_5_Upgrade_template_files"> Step 5: 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. Customized templates and skins need to be upgraded to the [[TWikiDocumentation]]. 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. +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]]. - 4. The Form Templates replace the TWikiCategoryTable: + 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. - 5. \_\_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=\_\_ - 6. 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. - 7. Restore any additional template subdirectories of your TWiki webs you might have and merge the changes. - 8. Test your TWiki installation to see if you can view topics. - -### <a name="Step_5_Upgrade_public_files"> Step 5: Upgrade public files </a> + 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. -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` +### <a name="Step_6_Upgrade_public_files"> Step 6: Upgrade public files </a> -* * 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"). +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_6_Upgrade_data_files"> Step 6: Upgrade data files </a> +### <a name="Step_7_Upgrade_data_files"> Step 7: 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>` +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` - 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:_** - 9. 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 + 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> |