Read Me

This is a tcl wrapper for pslib (pslib.sourceforge.net) version 0.2.5.

API
===
For the most part the pslib API documentation should apply.  Exceptions
to this are PS_symbol_name which should be called like this:

set symname [PS_symbol_name $psdoc $charcode $fontid $dummy $size]

The last two arguments are actually ignored, but I kept them to maintain
compatibility with the C API.

For functions that require floating point array arguments (PS_setpolydash
for example) I had to create some "helper" commands.  These commands
are new_float_array, float_array_setitem, and delete_float_array.  The
operation of these helper commands should be fairly self explanatory, and
you can find examples in examples/draw.tcl.  In case you don't feel like
looking, here is a quick code snippet.

...
set polydash [new_float_array 4]    ;# Create a 4 element floating point array
float_array_setitem $polydash 0 5.0 ;# polydash[0] = 5.0
float_array_setitem $polydash 1 3.0 ;# polydash[1] = 3.0
float_array_setitem $polydash 2 1.0 ;# ... you get the idea ...
float_array_setitem $polydash 3 4.0
...
PS_setpolydash $ps $polydash 4      ;# The polydash variable holds the array
...
delete_float_array $polydash        ;# Delete the array (important!)
...

Library functions that have not been implemented (yet) are:
  PS_hyphenate - Because I don't really understand it yet.  Besides,
    PS_show_boxed and other API commands usually handle the actual
    hyphenation details.
  PS_list_resource, PS_list_values, PS_list_parameters - These are
    mostly used for debugging the C API and they actually send stuff
    to stdout.  If they are useful I will make them return tcl lists
    instead.
  PS_open_mem, PS_get_opaque, PS_open_fp, PS_new2 - It should be fairly
    obvious why I didn't try to implement these.

Some notes about SWIG
=====================
The wrapper itself was created primarily with the SWIG interface generator
(www.swig.org).  I have included the swig files that I used to create the
wrapper (files ending in .i) so that
  1) wrappers for other languages can be created, and
  2) anybody who wants to modify this wrapper, and has SWIG installed,
     can do so.

There are three swig .i files:
  pslib.i - which simply includes other files.
  pslib-simple.i - which contains the definitions of the functions that
    didn't require modification.
  pslib-comples.i - which contains the definitions of the more complex
    functions (PS_symbol_name, for example, which passes it's result to
    the caller in a writeable argument).

The SWIG command I used to create pslib_wrap.c (the main tcl wrapper file)
was "swig -tcl8 -pkgversion 0.2.5 pslib.i".

How To Build
============
I haven't created a configure script or Makefile yet.  Sorry.  I have
included a shell script (build.sh) which contains the compile and link
commands that I used to build the wrapper.  You should be able to modify
the shell script for your environment by replacing the various paths and
such.  If you do this correctly you should get a shared library called
libpslibtcl0.2.5.so (you'll want to change the .so extension if your
OS uses something else of course - you'll also need to edit the
pkgIndex.tcl file accordingly).

Installation
============
To install the wrapper you need to do the following:

Note: My tcl installation expects to find modules in /usr/local/lib.
If yours looks for modules elsewhere simply change the commands below
appropriately.

% cp libpslibtcl0.2.5.so /usr/local/lib
% mkdir /usr/local/lib/pslibtcl0.2.5
% cp pkgIndex.tcl /usr/local/lib/pslibtcl0.2.5

Examples
========
I have translated some of the examples that are included with the primary
C distribution into tcl.  In some cases these are not particularly good
examples of tcl programming, but my aim was to make as literal a translation
from the original code as possible.

Other
=====
If you need help building or installing this you can contact me via email
at bbame@umm.edu.  Or, better yet, you can create the proper build files
(configure, etc.) and contribute them to the project.

Bill Bame
bbame@umm.edu
5/9/05