# $Id: README,v 1.31 2001/08/30 12:58:28 jerome Exp $
#
ZShell v1.3

(C) 2001 Jerome Alet <alet@unice.fr>

This program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.

============================================================

ZShell is an external Zope method which allows you to
manipulate the ZODB using standard unix shell's commands
from within Zope's Management Interface in your web
browser.

All commands do security checks and either work or exit
with a message, depending on your current privileges.

However, you should keep in mind that ZShell is very
powerful: use it carefully, do backups often, and use
Zope's Undo facility when needed.

If the use of ZShell leads to a data loss, your dog
being killed, or your wife/husband going away, then:

		YOU HAVE BEEN WARNED !!!

============================================================

Licensing terms:
----------------

	This software is under the GNU GPL but with the
following interpretation since mine differs from the FSF
one:

	1 - I allow you to use this software from Zope:

		- Install this external method in Zope.
		- Run it by clicking on the "Test" tab,
		  or directly accessing it from your
		  web browser.

	2 - I allow you to redistribute this software with
	    Zope in any way, provided that ZShell is distributed
	    with all its sources, this README file, the
	    LICENSE file, and the COPYING file.

	3 - If you plan to copy parts of my source code to
	    integrate it in your own software or in Zope's
	    core, then the GPL applies and the resulting
	    software must be redistributed under the GNU GPL.

	4 - If you plan to call my software from your code,
	    then your software must be redistributed under
	    the GNU GPL.

For further clarification, please read the file LICENSE
which should have been distributed along with this software.

IMHO my interpretation is OK with regard to the GPL FAQ, especially
the following sections:

	http://www.gnu.org/copyleft/gpl-faq.html#WritingFSWithNFLibs
	http://www.gnu.org/copyleft/gpl-faq.html#WindowsRuntimeAndGPL
	http://www.gnu.org/copyleft/gpl-faq.html#GPLPluginsInNF
	http://www.gnu.org/copyleft/gpl-faq.html#GPLAndPlugins

============================================================


Installation:
=============

	* Be sure to have at least Zope 2.3.x, ZShell may
	  not work with previous versions.

	* Download the jaxml GPLed Python module from:

		http://cortex.unice.fr/~jerome/jaxml/

	  and install it, following the instructions included
	  in its README file. This module is now necessary for
	  ZShell to work correctly.

	* Download ZShell's latest version from:

		http://cortex.unice.fr/~jerome/zshell/

	* Extract it somewhere on your hard disk:

		gunzip zshell-x.xx.tar.gz | tar -xf -

	  (replace x.xx with the version number)

	* Copy the zshell.py to your Extentions Zope directory:

		cp zshell-x.xx/zshell.py /usr/local/zope/Extensions
	  or:
		cp zshell-x.xx/zshell.py $INSTANCE_HOME/Extensions

	* In your Zope's management screen, add an External Method
	  object:

			   Id: zshell
			Title: The Zope Shell
		  Module Name: zshell
		Function Name: zshell

	* That's all.

	* You may optionally copy the zope-zshell.3 file somewhere
	in your MANPATH, this is Jim Penny's Debian manual page for ZShell.

Usage:
======

	* Access to the zshell object from your web browser.

	* Type your commands in the text area.

	* Click on the "Run !" button and look at the results.


Alternative:
============

	* You can now use ZShell from Andy McKay's ZShellCLI which is now
	part of this package. ZShellCLI allows you to access to ZShell
	directly from any Python interpreter. You'll find ZShellCLI in
	the ZShellCLI directory.

	* To use ZShellCLI you may have to edit xmlrpclibBasicAuth.py
	to set the path to the xmlrpclib.py module (usually in zope/lib/python),
	then just type:

		python ZShellCLI.py

	and read the online help.


Hints:
======

	* ZShell's man command is your best friend !

Enjoy !

Please email bugs or comments at: alet@unice.fr
