
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 tkholwb, you might execute:
		
		cp -pr TkHolWorkbench/PackageSkeleton ~/PackageSkeleton
		tkholwb \
			-package ~/PackageSkeleton \
			-otherpackage PackageSkeleton \
			-topwin PackageSkeleton

	The  first  option makes the package code available to
	Tk/Tcl,   the   second   adds   the   package  to  the
	"Packages" menu option in TkTheoryViewer.

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.

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 Starting a package using "runpackages".

	When  a  package  is  supplied  to  runpackages  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.

	Optionally, somewhere in the package the procedure

		proc <package-name>::Initialise { }

	may  be  defined. If it is not 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.

3.3 Processing arguments and closing a package

	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

	"runpackages"   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.

	This directory contains 6 packages.


	The  packages  dependency  graph is roughly as follows
	in this release:
			      
		 TkTheoryViewer	     TkGoalProof
		     |	      \__ __/    |     \           
		     |	       __X__ \___|_____	\
		     |      __/     \__  |     \ \
		 HolRichText	       Popups	 ScriptFiles
		     | 
		     |
		     |
	 	 TkHolSlave			    
		 
	Hmm...  not  a  very  clear or up-to-date diagram. See
	the  individual  documentation  for  each  package  to
	determine    its    dependencies.   Above   all,   the
	dependencies are guaranteed to be non-cyclical!!

	Thus  TkHolSlave  and  Popups  can be used as packages
	independent of the other packages.

