SCCS ID		@(#)README	1.1	7/26/94

This directory contains the source for the Tcl extension, "PBM", which
implements core parts of the Jeff Pozansker's Portable Bitmap Package (PBM)
as Tcl operations.  The operations that are included are useful for
dynamically generating bitmap images for the World Wide Web.

The manual page gives a complete description of the package.

The basic idea is that a new top-level Tcl object called a "pict" is
implemented.  Typically, these are created by reading from a PBM or GIF file
or by rendering text in a particular font.  Pict operations include cutting
out part of a pict, pasting one pict onto another, and writing a pict out to
a PBM or GIF file.

Picts can have a transparent background, which "does the right thing" when
one pict is pasted onto another.  Transparent GIF files are generated.

Text can be rendered in any font for which an X "BDF" font description is
available.  Two built-in fonts are available.  A good source of BDF files is
	ftp://ftp.x.org/pub/R5/mit-3.tar.Z
Warning: that file is huge (20MB).

tcl_pbm requires that you have the sources for "netpbm" package.  These are
available at
	ftp://wuarchive.wustl.edu/graphics/graphics/packages/NetPBM

This package expects PBMPLUS/netpbm of 1mar1994.  However, becuase it uses
most PBM sources files as-is, and contains patches to three source files, it
is quite likely that it will compile as-is with later versions of the PBM
package.


Files in this distribution
--------------------------

configure	Configuration script, generated by GNU autoconf.
		You should not need to modify this file.

configure.in	Configuration specification, used by GNU autoconf.
		You should not need to use or modify this file.  It is
		provided for dire configuration problems.

Makefile.in	Makefile template for the accessories and test programs.

pbm_tcl.[hc]	C headers and source for managing picts.
pbm_text.c	C source for handling text and fonts.
pbm_operation.c	C source for pict operations, such as cut and paste.
pbm_interface.c	C source for interfacing to PBM routines and handling errors.
pbm_util.c	C source for utility pict routines.

tclAppInit.c	Tcl_AppInit procedure for tcl_PBM (Tcl + PBM).

pbm.tcl		Example script that describes the tables in a database.

pbm.n		Manual page.

test/		Directory containing test scripts and data.


Files generated by the build procedure
--------------------------------------

libtcl_pbm.a	object library for adding to Tcl.

tcl_pbm		tclsh + PBM demo program.

config.status	Result of running "configure"; generates Makefile from
		Makefile.in.

libpbm.c...	symlinks and patched sources for PBM package.


Configuring, Compiling and Installing
-------------------------------------

The only unusual thing about this Tcl extension is that it must know where
the netpbm sources are.  You must create a symbolic link to the sources
named "PBM" in the source directory.  The Makefile will create other
symlinks to some PBM source files and use "patch" to modify other PBM source
files.

This release should compile and run with little or no effort on any
UNIX-like system that approximates POSIX, BSD, or System V

    (a) Make sure that this directory and the corresponding release of
        Tcl are both subdirectories of the same directory.

    (b) Type "./configure" in this directory.  This runs a configuration
	script created by GNU autoconf, which configures tcl_pbm for your
	system and creates a Makefile.  The configure script allows you
	to customize the configuration for your site;  for details on
	how you can do this, see the file "configure.info" that came with
	Tcl.

    (c) Type "make".  This will create a library archive called "libtcl_pbm.a"
	and an interpreter application called "tcl_pbm" that allows you to type
	Tcl commands interactively or execute script files.

    (d)	To test the library, a demonstration script (pbm.tcl) is included.
	Type "make test" to exercise it.

    (e) If the make fails then you'll have to personalize Makefile.in
        for your site or possibly modify the distribution in other ways.
	
    (f) Type "make install" to install the binary and library file in
        standard places.  In the default configuration, it will be installed
	in the same tree that the "tclsh" program is installed in.
	You'll need write permission on this directory.


Incorporating tcl_pbm into other Tcl interpreters
-------------------------------------------------

The PBM files should be installed in the same locations as the Tcl binaries,
libraries, and manual pages.  The configure script should set up the
Makefile appropriately.

To incorporate the pbm module into your program, add a call to
	Pbm_Init(interp);
to your AppInit() procedure.  Link your program with the option
	-ltcl_pbm
