README
======

NEW!
----

_After_ you built succesfully Gaby you may come back in this directory and
'make install-module'. This will allow you to use the Gaby module like any
other Python module (import gaby; ...)

Important note: this won't work if you compiled against GTK+/Gnome, you will
have to compile Gaby without GUI support: ./configure --disable-gui] and you
have to --enable-miguel-wishes

[this will be fixed. some day.]

BUG with PyApache
-----------------

Since Gaby was designed to load a database on startup and keep it till the end,
it is only possible to use gaby.load_database() once. This was not a problem
until I installed PyApache (the script was run then python finished) because
with PyApache python starts at the beginning and stays in memory till the end
of the time (ie not till the end of the script). And the second invocation of
load_database fails. I thought about a work-around but it would eat your memory
far too much to be acceptable.

[However there is a kludge: change the extension of Gaby scripts to .gpy and
edit your srm.conf:
	# you already have this:
	AddHandler python-cgi-script .py
	# the kludge:
	AddHandler cgi-script .gpy
]

SERIOUS BUG
-----------

Typical Python session:

 $ python
Python 1.5.2 (#0, Sep 13 1999, 09:12:57)  [GCC 2.95.1 19990816 (release)] on
linux2
Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam
>>> import gaby
>>> gaby.load_database('gaby')
>>> st = gaby.get_subtable_by_name('Address Book')
>>> ...
>>> quit
'Use Ctrl-D (i.e. EOF) to exit.'
>>> (Ctrl-D)
Segmentation fault
^^^^^^^^^^^^^^^^^^

while:
 $ python
Python 1.5.2 (#0, Sep 13 1999, 09:12:57)  [GCC 2.95.1 19990816 (release)] on
linux2
Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam
>>> import gaby
>>> import sys
>>> gaby.load_database('gaby')
>>> st = gaby.get_subtable_by_name('Address Book')
>>> ...
>>> sys.exit(0)

terminates ok.

Documentation moved !!!
-----------------------

The documentation of this Python plug-in is now available in DocBook format
(hence HTML, PostScript, ...) in the doc/ directory.

This file is here as an image of the past (but can still be used to get a quick
overview of what is done).

Brief introduction to script-fus
--------------------------------

The Python plug-in is a great step towards scripts-fus and thus to easy ways
to write extensions.

They can be used in several ways :

  - as actions (defined in a desc file) :

Begin actions
	Mail to ...
		!script_fu( AddressBook:E-Mail )
		#include mailto.py
	...

  - as actions (defined at run-time) :

[NOT YET really IMPLEMENTED] there is a 'home-brewed scripts' menu item that
allows to select in a file dialog box a script to run

  - as command-line scripts (thanks to gabyscript) :

<-- starts here -->
#! /usr/local/bin/gabyscript --as gaby --interpreter python

subtable = get_subtable_by_name('Address Book')

for i in subtable.fast_records_list():
	record = subtable.get_record_no(i)
	if ( len(record[7]) == 0 ):
		record[7] = 'Belgium'
	subtable.set_record_no(i, record)
<-- stops here -->

  - as scripts to be launched on startup :

(copy this to ~/.gaby/scripts/autoexec.gaby)

<-- starts here -->
# python

main_win = get_main_window()
st = get_subtable_by_name('Phone Book')
xlist_win = st.create_new_window( 'xlist' )

main_win.resize(400, 500)

main_win.add_bound_window(xlist_win)
xlist_win.add_bound_window(main_win)
<-- stops here -->

(the first line is used so Gaby knows it is a Python script)


but other ways are planned (with ideas going to rewriting views plug-ins in
python)

[note that when I speak about Python it's simply because it's currently the
only one interpreter available - things will work the same way with Perl, ...]

Python
------

There is actually a module called _gaby that provide a dumb way to do thing and
there _will_ be a module called gaby that will provide an object-oriented way
to do the same dumb things :) 
Update : the module is now called gaby and provide the oo-way.

Objects
.......

There are 2 new object types :

- GabyWindow:
(nothing to say here)

- GabySubTable:
it has a few attributes :
  - name : its name
  - i18n_name : its name translated in the current language
  - fields : a tuple with the names of the fields
  - i18n_fields : idem but translated in ...
  - table : the name of the table behind the subtable
it also has a few methods, documented in the source ...

Functions
.........

They are documented in the source code.

-- 
Frederic Peters - Sun, 10 Oct 1999 14:45:05 +0200
