
0. Contents

	1. Who this is for
	2. Introduction - Writing a package
	3. What is a "package"?
	4. Special kinds of packages.
	5. Standard TkHolWorkbench packages.

1. Who this is for

	This  information  is  for  anyone thinking of writing
	their   own   GUI   packages  to  cooperate  with  the
	existing packages supplied with this release.

2. Introduction - Writing a package

	A  skeleton  package is included in ./PackageSkeleton.
	It  is  a template for packages which define new types
	of  top  level  windows. To copy this package and use
	it with tkhol, you might execute:
		
		cp -pr TkHolWorkbench/PackageSkeleton ~/PackageSkeleton
		tkhol \
			-package ~/PackageSkeleton \
			-otherpackage PackageSkeleton \
			-win PackageSkeleton

	"-package"   makes   the  package  code  available  to
	Tk/Tcl,   "-otherpackage"  adds  the  package  to  the
	"Packages"   menu  option  in  TkTheoryViewer.  "-win"
	creates  a  top  level  window of the specified widget
	class.

3. What is a "package"?

	A  package,  in  its simplest form, is very similar to
	a  library  of  code,  say  a C library or a C++ class
	library.  The  code  is  tcl  code plus any other code
	loadable into a Tcl session.

	A package should have subdirectories
		src/	Tcl and other source files
		doc/	Documenation

3.1 Files in a package

	A  package  is  a  directory  containing  Tcl  code in
	*.tcl  files.  (Note:  Tcl has a notion of a "package"
	similar   to   this,   but   we   are   talking  about
	TkHolWorkbench  packages  here).  It may contain other
	code  and  data as well, e.g. ML code to load into the
	HOL  session  at runtime, or bitmaps to use for button
	displays.

3.2 Using a package

	When  a  package  is  supplied  to tkhol by a -package
	argument,  the  tcl  code  of  the  package  (in *.tcl
	files)  is  set  up  for  autoloading into tcl. Before
	this,  it  is  also  autoindexed if a -mkindex flag is
	also provided, or if no tclIndex exists yet for the
	package.

	NOTE:  Sometimes,  especially  during development, you
	will  have  to use the "-mkindex" option to remake the
	index  for  the  package,  which  will  be out of date
	once new functions have been added.

3.3 Processing arguments, Initialisation and closing a package

	Somewhere  in  the .tcl files in the src/ directory of
	the package the procedure

		proc <package-name>::Initialise { }

	may  be  defined. If it is not defined then no attempt
	is  made  to  call  it, and no error is generated. The
	package  name  is  simply  the  name of the directory,
	e.g. if the package spec is
		"-package
	./TkHolWorkbench/TkTheoryViewer",  then  
	the package name is "TkTheoryViewer".

	Initialisation  procedures  are called in the order of
	the package specifications on the command line.

	Also optionally  the  following  two procedures may be
	defined.  If  they  are not then no attempt is made to
	call them
	
		proc <package-name>::ProcessArgs { argv }
		
		proc <package-name>::Shutdown { }

	At  the  moment  ProcessArgs  does *not* have to strip
	out  used  arguments  and  return  the  argument list,
	although this may be added later.
	
	Shutdown  procedures  are called in reverse order when
	the  process  exits  by  normal  means  (i.e.  when  a
	DestroyNotify   happens  on  the  top  window  of  the
	application)

3.4 Variables defined by runpackages

	"tkhol"   automatically  defines  tcl  variables
	<PackageName>_library  and  <PackageName>_version  for
	each   package  specified  by  a  -package  flag.  The
	version   number   is   presently   taken   from   the
	TkHolWorkbench version number.
	
	
4. Special kinds of packages 

4.1 Proof packages
	
	Supply  a  -proofpackage  line to runpackages, as well
	as  a  -package  line  giving the full path. This adds
	the   package   to   the   "Theorems"   menu   of  the
	TkTheoryEditor, or the "current" theory window only.
		
	In  general  a  proof  package will provide facilities
	to  either  bind  the  resulting  theorem  to  and  ML
	identifier  in  the  underlying  HOL  session, or save
	the theorem to the current theory segment.
		
4.2 Definition generating packages
	
	Supply  a  -definitionpackage  line to runpackages, as
	well as a -package line giving the full path.
		
	This  adds  the  package  to the "Definitions" menu of
	the  TkTheoryEditor,  or  the  "current" theory window
	only.
		
	
	
4.3 Type definition generating packages
	
4.4 Axiom generating packages
	

5. Standard TkHolWorkbench packages.

	See the online documentation in
		doc/packages/packages.html  
	for  documentation  of  the  individual packages which
	currently exist in TkHolWorkbench.

