[Zope-PTK] Install documentation

[Tres Seaver]

Lucas Hofman wrote:
> 
> Tres,
> 
> I experience the install docs as confusing and possibly
> incorrect:

First, thanks for reporting these problems!

> 1. When installing PTK0.8.2 over a fresh Zope-2.2: A: The docs
> do not tell me the userid to use when unpacking the archive.
> This might be dependent on whether Zope is ment use use PCGI or
> not. I had to chmod all dtml files to allow zope (running as
> nobody) to read them.

This is a general issue with tar when run as root -- it preserves
(by default) the ownership of the original files, which is never
what you want when unpacking "foreign" software.

There is talk of a better system for packaging Zope products
(ZRPM, any one?);  until then, you'll need to make sure that the
user as whom Zope runs has read access to all "software", and
write access to the 'var' directory.  I don't believe that PCGI
changes that requirement at all.

>    B: Do one has to import Wizards.zexp and/or DemoPortal.zexp.
>    The docs do not instruct to, but the files are there. And
>    the README files tell you to import them. Doing so get you
>    an error (ID already in use), so I assume the README files
>    to be not correct.

The 0.8.2 version was an attempt at creating a "import-free"
distribution; it tried to distribute Wizard and DemoPortal (which
are "through-the-web" products) using the "Distribution tab"
method (which creates filesystem products).  Unfortunately, a
Zope misfeature caused the Wizard product initialization to fail;
when Zope 2.3 ships (maybe 2.2.3, as well), the distribution tab
will become feasible again.

In the meantime, you need to remove the DemoPortal and Wizard
*directories* from your Products directory (on the filesystem),
and restart Zope.  You should then be able to import
DemoPortal.zexp and Wizard.zexp into the Control_Panel/Products
folders (after moving/copying/linking them into the import
directory, of course :) 
> 2. When installing the PTK-0.9 upgrade: A: When unpacking in
> the Zope root one ends up with a ZopePTK-0.9.0-src directory in
> the root. Can't be correct.

The issue here is that not everyone wants to unpack into
'lib/python/Products'.  For instance, people using Zope's
INSTANCE_HOME feature (see
http://www.zope.org/Members/4am/instancehome) want it to unpack
to 'Products'.

>    B: After I move PTKBase, PTKDemo and ZCallable to their
>    correct location and fired up zope all products where OK.
>    The version properties are blank however. How to tell
>    whether the upgrade was succesfull. Do I need to import the
>    .zexp files?

There should be a 'version.txt' file in each directory, which
would populate that property when the product was imported.  That
file is *not* present in my sandbox;  I need to fix that.  WRT
the export files, you will still need to import DemoPortal and
Wizard, at least until the Zope misfeature I mentioned is
eradicated.

>    C: When trying to import I get the "id already in use"
>    error. Deleted the existing products and try again. No
>    errors this time. Version id 0.91 for the demoportal, 1.0
>    for the Wizard. Looks good.

Great.

>    D: After a restart version of demoportal is set back to
>    0.8.2.  Strange. Might have something to do with the
>    demoportal and wizard directories in Products. After
>    deleting those directories and re-importing the new .zexp
>    files the new version survive a reboot.

Distribution tab products do blow away imported ones, without
checking versions.

>    E: How to check whether everything is OK now?

Create a portal object, view it, join as another user, try
creating content, etc.  
> General: A: What is in the .zexp files, and why do they have to
> be there? Is is possible to look into them without installing
> them?

An export file is a series Python pickles (a transitive closure
of the exported object's contents); its format is defined in
$ZOPE_HOME/lib/python/ZODB/ExportImport.py.  While Jim Fulton can
probably eyeball pickles, most of the rest of us would need help.
A better alternative would be to redo the export, checking the
"As XML" option; the resulting file would at least be human
readable, although I still wouldn't recommend it as "beach
blanket" reading.

>    B: Include some simple tests along the way in the install
>    docs, to help the  first time installer determine whether
>    he/she is still on the right track.

Good point.

> It is very well  possible that these questions result from a
> lack of understanding about products, Zope or python. If that
> is the case, excuse me, but realize I am probalby not the only
> one..

Your feedback provides an excellent sanity check on my rather
feeble documentation efforts.  Thanks for detailing the problems,
instead of just throwing up your hands in disgust.  I will
incorporate your suggestions into the INSTALL documentation for
the next release.

Thanks again!

Tres.  --
===============================================================
Tres Seaver                                tseaver@digicool.com
Digital Creations     "Zope Dealers"       http://www.zope.org