Update README and TODO file

README.rst

@@ -26,17 +26,20 @@ What file should I use?
 
 All the .msi files are named as follows:
 
-    pygtk-all-in-one-X.X.X.win32-py2.6.msi
+    pygtk-all-in-one-X.X.X.winYY-pyZ.Z.msi
 
-Where X.X.X is the PyGTK All-in-one version number and
-Y.Y is the Python version number the installer supports.
+Where X.X.X is the PyGTK All-in-one version number, YY is 32 or 64 and
+Z.Z is the Python version number the installer supports.
+
+You need to make sure both YY and Z.Z correspond to the version of the Python
+interpreter that's installed on your system.
 
 Migrating from pycairo+pygobject+pygtk packages
 ===============================================
 
-If you have some or all of the separate pycaior, pygobject, pygtk, pygoocanvas,
-pygtksourceview2 or pyrsvg packages, please ensure they are uninstalled before
-you begin with the PyGTK All-in-one installer.
+If you have used some or all of the separate pycaio, pygobject, pygtk, pygoocanvas,
+pygtksourceview2 or pyrsvg packages before, please ensure they are uninstalled
+before you begin with the PyGTK All-in-one installer.
 
 The all-in-one installer does not check for their presence and will happily
 overwrite files that belong to the separate packages. If you forget to check
@@ -48,74 +51,123 @@ for this you risk the following scenario:
        - uninstall pycairo, pygtk and pygobject
        you now have a *broken* pygtk all-in-one installation
 
-Now would also be a good time to uninstall the gtk+ runtime you've used
-with the separate pyg* packages and to clean your PATH environment variable.
+This would also be a good time to remove the gtk+ runtime you've used with the
+separate pyg* packages and to clean your PATH environment variable.
+
+Note that pycaio, pygobject, pygtk, pygoocanvas, pygtksourceview2 and pyrsvg
+.exe installers (like any other .exe installer generated by distutils) sometimes
+leaves things behind when you uninstall them.
 
-Automatic installation
-======================
+Default installation
+====================
 
-An automatic PyGTK All-in-one installation automatically detects the correct
+A default PyGTK All-in-one installation automatically detects the correct
 Python installation directory and if Python was installed for all users or just
 yourself. These values are then used by the PyGTK All-in-one installer.
+To start a default PyGTK All-in-one installation, simply double click the
+.msi file or execute the following command from a Command Prompt (cmd.exe)::
 
-* If you want to generate a log file you can execute the following command from a
-  Command Prompt (change X to the correct version numbers)::
+    %WINDIR%\system32\msiexec.exe /i pygtk-all-in-one-X.X.X.winYY-pyZ.Z.msi
 
-    %WINDIR%\system32\msiexec.exe /i pygtk-all-in-one-X.X.X.winX-pyX.X.msi /l*v install.log
+Custom installation
+===================
 
-  Note that having an installation log is the only way we can provide help should
-  something have gone wrong.
+Like any other Windows Installer package, you can change how PyGTK All-in-one
+will be installed on you system by passing parameters and/or by setting
+public properties to msiexec. Execute `msiexec /help` for a list of options
+supported for all .msi installation packages.
 
-* If you do not want to generate an installation log file you can simply double
-  click the .msi file that matches the Python version where you want to install PyGTK All-in-one.
+Target directory
+----------------
 
-=============================
-Things you might want to know
+The TARGETDIR property determines the root directory of the PyGTK All-in-one
+installation. If this property is set, the PyGTK All-in-one installer does
+not automatically detect the installation directory of the Python interpreter
+installed on you system. For example, a custom installation directory can be
+specified with::
+
+    TARGETDIR=R:\pythonX
+
+Installation for All Users
+--------------------------
+
+The ALLUSERS property determines if PyGTK All-in-one should be installed for
+all users, or only for the user that initiated the installation. If you want
+to install for all users, set the ALLUSERS property to "1"::
+
+    ALLUSERS=1
+
+If you want to install for the current user only, you should not specify the
+ALLUSERS property at all. Hence, a per user installation is the default installation
+mode for custom installations. Note that "1" is the only valid value for the
+ALLUSERS property!
+
+You should combine this property with TARGETDIR. Setting ALLUSERS disables the
+automatic Python interpreter detection.
+
+Feature Selection
+-----------------
+
+The INSTALLLEVEL property determines what features are going to be installed. If
+the INSTALLLEVEL property is not set, it's value defaults to 1 which causes a
+basic set of features to be installed (gtk+ runtime, pycairo, pygobject and pygtk)
+
+If you set INSTALLLEVEL to 2 (or any number greater than 2), you instruct the
+installer to do a "complete" installation (all features will be installed).
+
+There is another method to control what features should be installed by controlling
+the ADDLOCAL, REMOVE, ADDDEFAULT, REINSTALL, etc properties. Check MSDN for more
+details.
+
+Other msiexec options
+---------------------
+
+Take note that if the PyGtk All-in-one installer is run with no or a limited
+UI (/q[n|b|r]) the automatic Python installation detection is skipped. In this
+case setting the TARGETDIR property is required. You can also set the ALLUSERS
+property if you want a system wide installation.
+
+The PATH environment variable
 =============================
 
-#. Make absolutely sure the separate pycairo, pygtk, pygobject, etc packages
-   are uninstalled. The all-in-one installer does not check for their presence
-   and will happily overwrite files that belong to them. If you forget to check
-   for this you risk the following scenario:
+The PyGTK All-in-one installer does not require you to fiddle with the PATH
+environment variable. The pygtk version that's installed with the all-in-one
+installer takes care of loading the bundled gtk+ runtime on the PATH environment
+variable on interpreter startup. As a consequence simply importing gobject,
+gtk, etc works out of the box. And as an added advantage there is no possible way
+multiple gtk+ runtime versions on your system or user PATH environment variable
+can interfere with pygtk all-in-one.
 
-       - install Python
-       - install pycairo, pygtk and pygobject
-       - install pygtk all-in-one
-       - uninstall pycairo, pygtk and pygobject
-       ... you now have a *broken* pygtk all-in-one installation
+Getting help
+============
 
-#. You no longer need to fiddle with the PATH environment variable. Ever.
-   The pygtk version that's installed with the all-in-one installer
-   takes care of loading the included gtk+ runtime on the PATH environment
-   variable on interpreter startup. As a consequence simply importing gobject,
-   gtk, etc works out of the box. As an added advantage there is no possible way
-   a different gtk+ runtime can interfere with pygtk all-in-one.
+If something doesn't work as expected, you'll need to generate a couple of log
+files before you'll be able to get help. It is simply impossible to determine
+why something went wrong without those log files!
 
-#. I lied. If you have used the separate pygtk, pygobject and pycairo installers
-   but decide to migrate to the pygtk all-in-one installer, now is a good time to
-   clean your system or user PATH environment variable.
+If something went wrong when installing, you'll need both
 
-#. If something doesn't work as expected:
+    - An installation log (install.log). Execute the following command from a Command Prompt (cmd.exe)::
 
-       - unsinstall pygtk all-in-one
-       - install pygtk all-in-one with the following command (from a "Command Prompt" aka cmd.exe)::
+        %WINDIR%\system32\msiexec.exe -i pygtk-all-in-one-X.X.X.winYY-pyZ.Z.msi /l*vx install.log
 
-           %WINDIR%\system32\msiexec.exe -i pygtk-all-in-one-2.22.X.win32-py2.X.msi /l*vx install.log
+    - An execution log (import.log). Execute the following command from a Command Prompt (cmd.exe)::
 
-       - then run Python with the following command (from a "Command Prompt" aka cmd.exe)::
+        python -v -c "import gtk">import.log 2>&1
 
-           python -v -c "import gtk">import.log 2>&1
+If something went wrong when uninstalling, you'll need an unistall log. Execute
+the following command from a Command Prompt (cmd.exe)::
 
-       - study both install.log and import.log...
+    %WINDIR%\system32\msiexec.exe -x pygtk-all-in-one-X.X.X.winYY-pyZ.Z.msi /l*vx uninstall.log
 
 =======================
 Installer build scripts
 =======================
 
 The pygtk-installer project provides a set of tools to build the PyGTK
 all-in-one installer and it's various dependencies.
-There are currently versions of the all-in-one installer supporting Python 2.6
-and Python 2.7.
+There are currently versions of the all-in-one installer supporting 32 bit
+versions of Python 2.6 and Python 2.7.
 
 Included tools:
 
@@ -124,7 +176,7 @@ Included tools:
 - build_bindings.sh: a tool that builds windows installer packages (both .exe
   and .msi) for pycairo, pygobject, pygtk, pygoocanvas, pygtksourceview and
   pyrsvg for each supported Python version.
-- build_installer.py: a tool that generates an all-in-one installer bundling
+- build_installer.py: a tool that generates the all-in-one installer bundling
   the separate .msi installers created by build_bindings.sh, the glade binaries
   created by build_glade.sh and various gtk+ runtime packages from
   ftp.gnome.org/pub/GNOME/binaries/win32/.

TODO

@@ -1,18 +1,4 @@
-- Finish the feature tree (it currently doesn't represent
-  the actual dependency tree).
-
-- Detect the presence of the separate pyg* .exe and .msi
-  installers (we wouldn't want to overwrite them...).
-
-- As the all-in-one installer is based on a Python 2.7
-  distutils generated .msi file, it offers the possibility
-  to install into multiple Python installations.
-  That's great for pure Python modules/packages where you
-  can install the package into python 2.6, 2.7, 3.1, etc
-  at once. It isn't really applicable for c extensions
-  though. Removing that capability would simplify thing
-  a lot (but we should retain some choise in the form of
-  "install into automatically detected python" or "user
-  specified directory")
-
-- The dialogs used in the installer could use some work...
+- Open .glade/.ui files with glade3?
+- Run everything from reconfig.cmd in a post-install CustomAction.
+  See https://github.com/mono/win32-installers/blob/master/modules/gtk%2B-2.0-lib/gtk%2B-2.0-lib.wxs
+  for inspiration...