# $Id: README,v 1.41 2002/09/06 09:08:15 jerome Exp $
#
ZShell v1.60

(C) 2001-2002 Jerome Alet <alet@librelogiciel.com>

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.


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

  From version 1.60 on, ZShell includes some code which
  is copyrighted by Python Software Foundation.
  See the file python-licensing which is included in this package.

  The code in question is essentially a mix of the Python 2.1
  and 2.2 glob.py module's code, modified to integrate with
  the Zope Object Database semantics.

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

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 !!!

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

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://www.librelogiciel.com/software/

          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://www.librelogiciel.com/software/

        * 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.

        * Since version 1.4, you can now set, unset, and use
          variables on the command lines :

            - you can now set variables typing commands like :

                var=value

                (one per line)

            - or :

                setenv [--zope] var1=value1 var2=value2 ...

            use the unsetenv command to unset vars.

            to use a variable on the command line, just prefix
            its name with a dollar sign, e.g. :

                 F1=/folder1
                 setenv F2=/folder2
                 mkdir $F1 $F2
                 unsetenv F1 F2

                 this one will create the folders folder1 and folder2 in /

            another example :

                 exec ls -la $INSTANCE_HOME/Products

                 this one will give you the list of additional
                 Zope products you have installed.

          Available variables are Zope's running environment ones, plus
          all the variables defined in the current REQUEST object (each
          viewed as its string representation)

          Explanations about the --zope parameter are available using
          ZShell's man command : it causes variables to be persistent
          because it directly modifies Zope's running environment
          (be careful with that).

Alternatives:
=============

  ZShellCLI :
  -----------

        * 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.

  Zope's Management Interface :
  -----------------------------

        * You can now use ZShell directly in the normal ZMI :

          * install ZShell somewhere with the id 'zshell'

          * apply the patch main.dtml.patch to zope/lib/python/OFS/dtml/main.dtml
            This was tested with Zope 2.5.0-4 (Debian package) but this
            is really straightforward to adapt it to other versions.
            Here are the commands to type :

              $ cd /usr/lib/zope
              $ patch -p0 <~/zshell-1.50/main.dtml.patch

            Then restart Zope.

          * You can now type ZShell commands in the ZMI !!!
            You are currently limited to one command line at a time, but you
            may separate multiple commands with the ';' char.
            Commands won't do any output, so ls won't output anything for
            example, but all commands work anyway !

        WARNING : This may be incompatible with other products which
                  also patch the ZMI. I've proposed a solution to this
                  problem, but so far I haven't received any comment
                  which might have led me to finally code it.

Hints:
======

        * ZShell's man command is your best friend !

Enjoy !

Please email bugs or comments at: alet@librelogiciel.com
