Contents:
---------

1. Copyright and contact information
2. Introduction
3. Installation on Linux using the GUI installer (only on PC)
4. Manual installation on UNIX or Linux
5. Installation on Windows XP


1. Copyright and contact information
-------------------------------------

Postgres Forms (pfm) is a client application for PostgreSQL.

Copyright (C) 2004 Willem Herremans

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

A copy of the  GNU General Public License is included in the 'doc'
subdirectory of this software package.

Please send bug reports and feature requests via the corresponding
facilities on the home page of Postgres Forms (pfm):

http://gborg.postgresql.org/project/pfm/

Please send all other comments or questions to the mailing list:

pfm-comments@gborg.postgresql.org

or directly to me:

willem.herremans@tiscali.be


2. Introduction
----------------

Postgres Forms (pfm) has been designed and tested on Linux. It may
work on other UNIXes as well. It has also been tested on Windows XP.

To get Postgres Forms (pfm) running you need to have access to at
least one database on a PostgreSQL database server, which may be
running either on your machine, or on another machine that you can
access via TCP/IP. You also need the PostgreSQL client application
'psql' on your machine. See PostgreSQL documentation for details.

Postgres Forms has been designed and tested with PostgreSQL version
7.4.2, but it probably works with some older and newer versions as
well. It has also been tested with PostgreSQL 8.0. You can obtain
PostgreSQL from http://www.postgresql.org.

You also need one of the packages: Pgtcl or pgintcl to communicate
with the PostgreSQL database server.

Two versions of pgintcl are included in the pfm distribution: 1.5.0
and 3.0.0.

Pgtcl can be obtained from:

http://gborg.postgresql.org/project/pgtclng/projdisplay.php

pgintcl (included in pfm distribution) can be obtained from:

http://gborg.postgresql.org/project/pgintcl/projdisplay.php

Notes:

    - If you intend to use pgintcl, the 'tcpip_socket' connection
      parameter has to be set 'true' in postgresql.conf. This can be a
      security risk. See PostgreSQL documentation for details.

    - The Pgtcl package offers better performance, but needs to be
      built, whereas the pgintcl package is just a Tcl script that can
      be called by pfm.

    - If the pgin.tcl file is present in the installation directory,
      pfm sources it and does not attempt to load the Pgtcl package.

    - Postgres Forms has been designed and tested with versions 1.5.1
      of package Pgtcl and with versions 1.5.0 and 3.0.0 of pgintcl.

    - pgintcl 1.5.0. works with PostgreSQL version 6.4 or
      higher. pgintcl 1.5.0 only works with database character
      encoding LATIN1.

    - pgintcl 3.0.0 works with PostgreSQL version 7.4. or higher.

    - A copy of both pgintcl 1.5.0 and pgintcl 3.0.0 is included in
      the pfm distribution.

Postgres Forms has been designed and tested with Tcl/Tk version 8.4.

From version 1.1.1 on, pfm does no longer require the package
Iwidgets.

You can do one of the following to get the proper Tcl/Tk run time
environment:

   1. If Tcl/Tk is already installed on your system, you can let pfm
      use them.

      Note: You can verify the presence of Tcl/Tk as follows. At the
            command prompt type 'tclsh'.  You should get a '%' prompt.
            To see the version, type 'info tclversion' at the '%'
            prompt. You should get 8.4. Then type 'package require
            Tk'. You should get 8.4 and an empty window titled
            'tclsh'.

   2. If you are on a PC with either Linux or Windows XP, you can use
      the Tclkit run time environment which is included in the pfm
      distribution.

   3. For other UNIXes, you can download a precompiled tclkit from

      http://www.equi4.com/tk/download.html

      Install it in PARENT/pfm-x.x.x/tclkit and rename it to 'tclkit'.

      Note: pfm needs a 'tclkit' anyway, even if Tcl/Tk is installed
            on the system. The reason is that pfm explicitly calls the
            tclkit for running cat.kit, which it needs for capturing
            the error messages sent by psql. So, for UNIX platforms
            other than Linux on PC, it is necessary to download and
            install a tclkit.

   3. You can install the ActiveTcl distribution, that you can
      download from

      http://www.activestate.com/Products/ActiveTcl/

      which includes much more than what you need for pfm.


3. Installation on Linux using the GUI installer (only on PC)
-------------------------------------------------------------

You can either install pfm at system level, such that it is available
for all users, or at individual user level. The installation procedure
is the same, unless specified otherwise.

  1.  For a system installation login as root.

  2.  Put the pfm-x.x.x.tar.gz file in the directory in which you want
      to install the pfm-x.x.x directory and its subdirectories. This
      directory will henceforth be referred to as PARENT.  For a
      system installation PARENT could be /opt or /usr/local; for an
      individual user installation PARENT could be the user's home
      directory (~). Wherever 'PARENT' occurs in the following,
      replace it with the real name of that directory.

  3.  cd to PARENT and unpack pfm-x.x.x.tar.gz:

      tar --extract --gunzip --verbose --no-same-owner --file=pfm-x.x.x.tar.gz

  4.  This creates the directory PARENT/pfm-x.x.x which contains all
      the required files.

  5.  cd to PARENT/pfm and run the install program by typing

      ./install

      on the command line.

      Note: It is important that you run this command from the pfm
            directory (PARENT/pfm-x.x.x).

  6.  This starts the GUI install program. Choose the appropriate
      values for the options and press "Finish"

  7.  The GUI install program does 2 things:

          - It writes a launch script with name 'pfm', in a directory
            of your choice. This enables you to launch pfm by just
            typing 'pfm' on the command line (on condition that the
            pfm launch script was written in a directory in your
            PATH).

          - It creates a symbolic link named 'pgin.tcl' in the
            pfm-x.x.x dir either to pgintcl 1.5.0 or pgintcl 3.0.0, or
            it deletes such a link when you have chosen to use Pgtcl.

      Notes:

         - If you already had a script called 'pfm' in the directory
           that you have chosen, the installer program renames it to
           pfm.bak, or pfm.bak1, pfm.bak2, ...etc.

         - If you already have another script called 'pfm' in another
           directory in your PATH, you may have to delete it, or
           rename one or the other. You can verify which script is
           'active' by typing 'which pfm' on the command line. The
           result should be the fully qualified filename of the pfm
           script installed by the installer program.

  8.  This completes the installation. If it was an installation at
      system level, all users can start pfm by typing 'pfm' on the
      command line. If it was an installation at user level, only the
      user who installed it can start pfm.

  9.  Open the database on which you want to use pfm.

 10.  You will be asked if you want to install the pfm_* tables. Answer
      "yes".

 11.  If the database that you are opening already contains the pfm_*
      tables from a previous version of pfm, you will be asked if you
      want to convert the pfm_* tables. 

      WARNING: Before answering "yes" to this question, make sure that
               you have a backup of your database. There is a
               conversion SQL script from lower to higher version, but
               not from higher to lower version.

 12.  You are ready to use pfm. More documentation is found in the
      on-line help-file.

Notes:

   - The on-line help is the file 'help.html' in the
     PARENT/pfm-x.x.x/doc directory. It can be viewed by a web
     browser.

   - You can run the GUI install script at any time to modify the
     choices you have made before.


4. Manual installation on UNIX or Linux
---------------------------------------

  1.  Do steps 1 throygh 4 of the previous section.

  2.  cd PARENT/pfm-x.x.x

  3.  Configure the interface with PostgreSQL:

      a) If you have Pgtcl installed on your system and you want to
         use it:

	 rm pgin.tcl

	 Note: If pgin.tcl does not exist in this directory, you can
	       jump to step 4.

      b) If you want to use pgintcl version 3.0.0:

         ln -s pgintcl-3.0.0/pgin.tcl pgintcl

      c) If you want to use pgintcl version 1.5.0:

         ln -s pgintcl-1.5.0/pgin.tcl pgintcl

  4. If your system is not a PC running Linux, download a precompiled
     tclkit from

     http://www.equi4.com/tk/download.html

     Install it in PARENT/pfm-x.x.x/tclkit and rename it to 'tclkit'.

     Note: pfm needs a 'tclkit' anyway, even if Tcl/Tk is installed on
           the system. The reason is that pfm explicitly calls the
           tclkit for running cat.kit, which it needs for capturing
           the error messages sent by psql. So, for UNIX platforms
           other than Linux on PC, it is necessary to download and
           install a tclkit.

  5.  Make a launch script, named pfm, in a directory in your PATH:

      a) If you have Tcl/Tk on your system, and if you want to run in
         this environment, the launch script should contain the
         following lines:

         #!/bin/sh

	 tclsh PARENT/pfm-x.x.x/pfm.tcl PARENT/pfm-x.x.x

      b) If you want to use the Tclkit included in the pfm
         distribution instead (only included for Linux on PC), the
         launch script should contain the following lines:

	 #!/bin/sh

	 PARENT/pfm-x.x.x/tclkit/tclkit PARENT/pfm-x.x.x/pfm.kit PARENT/pfm-x.x.x

  6.  Don't forget to chmod a+x pfm

  7.  This completes the installation. If it was an installation at
      system level, all users can start pfm by typing 'pfm' on the
      command line. If it was an installation at user level, only the
      user who installed it can start pfm.

  8.  You can now continue with steps 9 through 12 of the previous
      section to get started with pfm.


5. Installation on Windows XP
-----------------------------

You can either install pfm at system level, such that it is available
for all users, or at individual user level. The installation procedure
is the same, unless specified otherwise.

  1.  For a system installation login as a user with administrator
      rights.

  2.  Select the pfm-x.x.x.zip file in Windows explorer, right click
      to open the context menu and choose "unpack everything". This
      launches the Windows unzip wizard which allows you to choose a
      target folder, which will henceforth be referred to as
      PARENT.  For a system installation, PARENT could be 

          "C:\Program Files".

      For an individual user installation for user_x, PARENT could be
      the user_x's home folder:

          "C:\Documents and Settings\user_x"

      Wherever 'PARENT' occurs in the following, replace it with the
      real name of that folder.

  3.  Now open the folder PARENT\pfm-x.x.x in Windows explorer, right
      click in that folder to activate the context pop-up menu and
      select "New -> Shortcut". Then browse and select
      "PARENT\pfm-x.x.x\tclkit.exe" as target. Then append pfm.kit,
      such that the "target" entry becomes:

          "PARENT\pfm-x.x.x\tclkit.exe" pfm.kit

      Then choose "pfm.exe" as name for the shortcut.

      After having installed this shortcut right click on it and
      select "properties". Verify that the target is

          "PARENT\pfm-x.x.x\tclkit.exe" pfm.kit

      and that the "Start in/from" property is

          "PARENT\pfm-x.x.x"

      The last property is important for pfm in order to find all the
      necessary files such as on-line help and pgin.tcl.

      Opening this shortcut will launch pfm.

  4.  You can now copy the "pfm.exe" shortcut to other locations such
      as the desktop and/or the Menu Start:

      "C:\Documents and Settings\All Users\Menu Start\PostgreSQL"

      for easy starting of pfm. 

  5.  Now you will have to modify/verify a few of the pfm options by
      choosing the menu 'Tools -> Options':

          - browser: By default it is Internet explorer, but you may
                have to modify this option to the actual location of
                Internet explorer on your PC. You can also choose an
                alternative browser, such as mozilla or Firefox.

          - psql: This must become the complete filename of 'psql.exe'
                which is something like:

                C:\Program Files\PostgreSQL\x.x\bin\psql.exe

          - printcmd: The program that you will use for printing the
                results of queries and reports. The default program is
                wordpad.exe, but you may have to modify this option to
                the actual location of wordpad.exe on your PC. You can
                also choose another program such as Word or Notepad.

  6.  This completes the installation.

  7.  Open the database on which you want to use pfm.

  8.  You will be asked if you want to install the pfm_* tables. Answer
      "yes".

  9.  If the database that you are opening already contains the pfm_*
      tables from a previous version of pfm, you will be asked if you
      want to convert the pfm_* tables. 

      WARNING: Before answering "yes" to this question, make sure that
               you have a backup of your database. There is a
               conversion SQL script from lower to higher version, but
               not from higher to lower version.

 10.  You are ready to use pfm. More documentation is found in the
      on-line help-file.

Notes:

    - The on-line help is the file 'help.html' in the
      PARENT/pfm-x.x.x/doc directory. It can be viewed by a web
      browser.

    - I have written this text based on the behaviour of a Dutch
      version of Windows XP. This means that I don't know the exact
      words used by the English version of XP.

    - pgintcl-3.0.0 has been pre-installed as interface with
      PostgreSQL. If you would prefer pgintcl-1.5.0 instead, delete
      the file 'pgin.tcl' from the folder "PARENT/pfm-x.x.x" and
      replace it with 'pgin.tcl' from the folder
      "PARENT/pfm-x.x.x/pgintcl-1.5.0". If you have Pgtcl installed
      and if you want to use it, just delete the file 'pgin.tcl' from
      the folder "PARENT/pfm-x.x.x"

    - If you have Tcl/Tk installed on your system and if you would
      prefer to run pfm using that instead of the 'tclkit', you have
      to make the shortcut pfm.exe as follows.

      Right click in the folder "PARENT/pfm-x.x.x" and select "New ->
      Shortcut". Then browse and select "C:\Tcl\bin\wish.exe" as
      target (if that is where your Tcl/Tk is installed) and append
      pfm.tcl such that the target entry becomes:

          "C:\Tcl\bin\wish.exe" pfm.tcl

      After having installed this shortcut right click on it and
      select "properties". Verify that the target is

          "C:\Tcl\bin\wish.exe" pfm.tcl

      and that the "Start in/from" property is

          "PARENT\pfm-x.x.x"

      The last property is important for pfm in order to find all the
      necessary files such as on-line help and pgin.tcl.

      Opening this shortcut will launch pfm.

