Item8640: Add documentation about the new Extension installer behavio…

…r, and the optional dependency on Archive::Zip.

git-svn-id: http://svn.foswiki.org/trunk@7052 0b4bb1d4-4e5a-0410-9cc4-b2b747904278

core/data/System/InstallationGuide.txt

@@ -337,8 +337,42 @@ Foswiki:Extensions is an extensive library of [[plugins]] for Foswiki that enhan
 
 In the _Extensions_ section of the =configure= page, you can select the _Find More Extensions_ button to download and install additional plugins from the foswiki.org website. If you are behind a firewall or your server has no access to the Internet, you can also install plugins manually. Installation instructions for each plugin are located in its corresponding topic on http://foswiki.org/. Additional documentation on Foswiki plugins can be found at Foswiki:Support.PluginsSupplement.
 
+When installing an extension from the =configure= interface:
+   * Even if available, local Extension installers and archives are not used
+   * The extension is downloaded from the configured archive
+   * If the extension is already installed, a backup is taken to the =working/configure/backup= directory
+   * Dependencies on other Extensions are automatically resolved and installed
+      * Dependencies are downloaded from the _same archive_ where the Extension was found.  No additional searching is performed.
+   * CPAN dependencies and other external packages are *not* resolved and should be resolved manually
+   * After installation, the Extension =_installer= module is saved in =working/configure/pkgdata=
+
+When installing extensions from the command line:
+   * The =_installer= package must be run from the root directory of the Foswiki installation. 
+   * The Extension =_installer= module must be downloaded from the Extension repository. The extension archive will be downloaded if required.
+   * When the =_installer= is run, it will install the Extension and dependencies similar to the =configure= interface except:
+      * You will be given the option to use local archives if available in the root of the Foswiki installation
+      * You will be given the option to resolve CPAN dependencies after the Extensions and dependencies are installed.
+      * Any other dependencies still need to be manually resolved.
+
 Plugins are activated in the _Plugins_ section of the =configure= page. In addition, some plugins are also configured in this section.
 
+---+++ Removing (uninstalling) extensions
+
+The web and command line interfaces can also be used to uninstall extensions.  When an extension is remove, the following occurs:
+   * The =_installer= package is used to recover the manifest.  If it cannot be found locally, it will be downloaded from the configured extension repository
+   * A backup of the previously installed files per the manifest will be taken to the =configure/working/backup= directory
+      * Note: If download of the =_uninstaller= was required, the backup will be made per the _current_ manifest.  It is preferable to always save the =_installer= modules.
+   * The Extension files will be removed, including the =_installer=. 
+      * Any additional files saved locally are not removed.
+   * Plugin modules __are not disabled in the configuration__ - they must be disabled manually.
+
+---++ Restoring a removed, or previous version of an extension
+
+The backup can be extracted from the root directory of the Foswiki installation.  The archive is taken "relative" to the root of the installation, so an =unzip= or =tar -xzf= of the backup file should be all that is required:
+   * =cd /root/of/foswiki=
+   * =tar -zxvf * working/configure/backup/[Extension}-backup-[yyyymmdd]-[hhmmss].tgz=
+or
+   * =unzip working/configure/backup/[Extension}-backup-[yyyymmdd]-[hhmmss].zip=
 ---+++ TWiki Compatibility
 
 Foswiki is 100% backwards compatible with TWiki<sup>&reg;</sup> markup up to and including TWiki 4.2.4. Existing TWiki webs, topics and attachments can be used with Foswiki without requiring any changes.
@@ -407,6 +441,7 @@ The following Perl modules may be used by Foswiki. See Foswiki:Support.HowToInst
 
 | *Module* | *Preferred version* | *Description* |
 | Archive::Tar | | May be required by the Extensions Installer in configure if command line tar or unzip is not available |
+| Archive::Zip | | Alternative to Archive::Tar, used by the Extensions Installer if Archive::Tar also unavailable |
 | CGI::Cookie | &gt;=1.24 | Used for session support |
 | Digest::base | | |
 | Digest::SHA1 | | |