Implementation
===============

	 The basic implementation consist of a tcl program with callbacks to
the sather compiler.  The compiler front end generates the required
tables and creates the tk interface. The tk interface then runs, calls
back to the sather compiler for information of various types.

	The sather portion of the program basically consists of
wrappers that generate the necessary graphs, using some canonical form
for class names.

	Set Help/Files for information on what's in which files.
	I have not extended either tcl or tk. The tkKit adds the
tkkit_cb command to allow callbacks to sather.  

 	All blame for the coding style must rest with me. This was my
first tcl program, and I can see that errors in coding style have made
the size of the browser gradually bordering on the unmanageable.  I've
made some naming changes that will hopefully make the tcl code more
understandable.

Customization
-------------
	During startup, the browser will source the file .bsConfig.tcl
in the user's home directory, if such a file exists/has been saved by
a call to save configuration.  You can have your own customization
stuff in a .bsCustom.tcl. Please see the help on customization.

Menu items
----------
	The menu items are set up in the procedure menuBarCreate, which
is quite easy to follow.  


Naming
------
	Making things understandable in tcl depends a lot on naming
conventions.

Globals: 	
All start with a lower case g as in gCurNodeName 
Many are private to a single pane, and are found in that pane's file

Procedures:
Usually start with the name of the pane they are associated with
i.e. graph,classList,featureList and text.

Pane separation:
In general, each pane has a create, init, update, addMenu and saveState
routine.
Each pane <p> is its own "class" and all procedures relating to that pane
are stored in a file called browser<p>.tcl, and have the prefix <p>.
The panes are graph history classList featureList text. The inform pane
is trivial and in the main (browser.tcl) file.

Global Name		File		 Prefix	               Doc
-------------------------------------------------------------------------
gGraphFrame		browserGraph.tcl graph<Function Name>  Help/graph
gClassListFrame		... similarly ...
gFeatureListFrame	... similarly ...
gTextDisplay		browserText.tcl	 text<Function Name>   Help/text
gHistoryFrame		browserHistory.tcl ....

Documentation for each of the panes may be found in the help directory.

Updating Panes: 
When a change takes place (such as a selection) the change is noted
appropriately (usually just setting the value of gCurNodeName - see
updateAll) and	one or more of the update* procedures are called.

Creating Panes:
Panes are created in procedures that start with <paneName>Create

Node names and "full" node names:
	With modules, the name that is displayed must be different
from the "true" name, which is a file path. "full" node names refer
to these module file paths. Sather understands and expects these
paths, not the truncated module name.  Full and regular names
are identical for classes.

	
Icon Bitmap
-----------
	The icon bitmap for the sather browser is specified in
browserConfig.tcl The bitmap (sather.xbm) and the bitmap mask
(sathermask.xbm) must both be specified.



Notes on TkKit
==============
 The value that comes from a callback is a list of return values.
Often you will have to extract the 0 the element [lindex ret 0]
to get the value you want (i.e. the whole tcl list is just the first
element of the array that is returned)

IDEAS
======
* Any use for being able to display the call graph?
* Minas: Communication with the debugger using send
* Communication also with the compiler (for error messages). This
will probably happen in some future release.

Various graph manipulation features. In general, one can sink an
enormous amount of time into graph viewing. I don't think it's worth
it.  A better option would be to hook into some standard tool like vcg
or dot. In any case, some possibilities:

Basic fixes:
* Proper drawing of arrow heads with the correct size. 
(note: it is possible to do everything correctly by not using
tcl's canvas "scale" primitive.  However, zooming in and out
then becomes unacceptably slow).

Advanced stuff - probably better to use something like VCG:
* Graph Movement: dBailey suggests the ability to hold down shift and move
    connected components. 
* A way to zoom further into the graph - a "magnification box"?
* Ways to collapse and expand parts of the hierarchy
* Notion of collapsing edges into a node - mark the node when this is
* done. Nodes which are left with no connections are moved to singl list
*? The ability to save and reload node positions. This made sense when
the whole graph was always viewed. Not sure if it makes sense anymore.

Done
----
* Use of TkIcon -maybe, but a lot of installation to do...
* Use of dotty to generate graph layout in general, and use in the browser
in particular.
* A way to dump the graph as postscipt
* A "documentation" feature that will allow the user to view features
and the associated comments (not all the code). 
* Using jstools? Looked into it. No
* Using xfemacs? see below. Ditto
* Using gnuserv - need to find out where it can be obtained...
   emacsclient is built in?
* Drawing the graph in the middle of the canvas, so that you can
scoll to the left as well as to the right after zooming in.
Tried setting the scrollbars, which almost works, but you sometimes
lose the graph altogether after scrolling! 


