Tutorial for @@NAME@@ @@VERSION@@

WHAT IS PTUI?

Python/Tkinter User Interface is my attempt to create an environment
where you can run code from within the tk mainloop like the wish
interpreter.  PTUI uses a small framework of classes that could be
imbedded into a larger application to facilitate rapid developement
and testing.

PTUI is gaining features of an integrated developement environment.
It has an object browser, highlighting of errors, auto-indentation,
and syntax highlighting.


HOW DO I USE PTUI?

Installation Instructions

First off you need Python 1.4.  Earlier versions may work, but you'll
need to hack the code.  Tkinter, an interface to the platform
independent windowing portion of Tcl/Tk, is also required.  For this
you will need Tcl/Tk version 7.4/4.0 or greater (not including 8.0).


To install in a Unix-like environment, unpack the distribution archive
and create an alias somewhere in your path pointing to the ptui
script.  I do this on my MkLinux machine by:

	ln -s /usr/local/python/ptui-1.0/ptui /usr/local/bin/ptui

If you want to customize things, copy the defaults.py file to ~/.ptui
and create an alias (syntax may very, this is for bash):

	alias ptui="ptui -i ~/.ptui"

The -i flag will run the next arg as an initialization script.


Under a Macintosh unpack the archive using the macintosh versions of
gzip and tar.  Python should be installed correctly.  You will need to
download Tcl/Tk version 7.5/4.1 (7.6/4.2 may work as well).  You can
use the scripts distributed with the macintosh version of Python to
convert the type of the scripts to be Python documents.  You may need
to rename ptui to ptui.py for this to work.  After you have done this,
you should be able to use the ptui script just like any other application.


I am completely unfamiliar with any Windows versions of Python,
Tcl/Tk, and Tkinter.  If you can recommend a way to install ptui, I
will be glad to put it here.


The Basics

With the installation all taken care of you should be all set to use
ptui.  If you have used Emacs or other Unix programs, you may already
be familiar with many of the keyboard shortcuts.  If you are using
ptui on a non-Unix platform many of its characteristics will seem
strange.  This is due to Tcl/Tk's origin as a X-Windows/Unix
scripting language.

I will take the liberty of assuming that you know Python and have at
least used another editor and the shell interpreter.  Ptui was not
created for beginners, but you may be alright if you are just starting
out.

The basic format of the Ptui window should be fairly familiar to you.
There is a menu bar with File, Edit, Buffers, Scripts, and Help
menus.  Take a minute to look through each menu and see what is
available.  Under the menu bar is an area we'll call the toolbox.
Inside the toolbox are several button shortcuts for commonly used menu
options.  Go! is the most basic and executes the buffer.  The others
will be encountered latter.

You will notice that any code you type into the input window will be
indented and colored properly based on the rules of Python.  One thing
that you will notice is that the auto-indentation code is a bit
naive.  It will not recognize a multi-line expression.  In this case,
manually indent or end the line with a "\" character.  The coloring
finds comments, strings, and keywords and formats them in a different
font from the normal text.

The basic unit in Ptui is the buffer.  Each document you edit exists
as a buffer.  Associated with each buffer is a namespace where you
program's code can exist.  Each time you execute the buffer, this
namespace is updated as well.  This is similar to the shell
interpreter's approach, but since you can edit entire files at a time,
Ptui makes it considerably easier to edit multiline entries.  Unlike
importing a module, all of the code gets executed and updated in a
buffer.

Using the modularize feature, you can create a module from a buffer.
This module will be inserted in sys.modules where any other code can
access it.  In this way, buffers can communicate through modules.
This can be usefull if you are editing a script that depends on
modules under developement.  When you make a change in the dependent
buffer, execute it, and modularize it, the updates will be available
to the script.  Modularize will create a module from a buffer if the
module does not currently exist.  If the module exists, the contents
of the buffer will be added, possibly overwriting previously existing
variables.  This module will not be updated if you rexecute the
buffer.  You must use the modularize feature again. 

