			Implementation Notes
			       on the
			    moog client


These notes (based on the Xgopher implementation notes by Allan
Tuchman) describe moog version 0.0, written in October 1992.
The author can be contacted at:

	Martin Hamilton
	Department of Computer Studies
	Loughborough University of Technology
	Leics. LE11 3TU, UK

	Voice:     +44.(0)509.224151
	E-Mail:    M.T.Hamilton@lut.ac.uk



Source Organization
-------------------
The moog source files are organized by function.  They are:

    xgopher.c - main program, initialize X, set up initial request.
    list.c    - create and maintain all gopher item and gopher directory
		data structures.  This provides the backbone of moog.
    util.c    - does gopher processing, get and process gopher requests
    misc.c    - misc things like time functions that may be host dependent
    net.c     - open, read, and write from a network connection
    help.c    - manage help file data.

   ------  No file above here has any connection to the X window system -----

    gui.c     - interface between the previous files and X functions
    options.c - retrieve application resources
    cso.c     - create, manage, and process requests for CSO name servers
    index.c   - create and manage panel to get keywords for index searches
    panel.c   - create and manage the main moog panel
    error.c   - create and manage the error pop up
    save.c    - create and manage the file save pop up and functions
    text.c    - create and manage the text display pop ups


The include files are used to provide functions definitions, 
configuration options, data structure declarations, share data,
and define bitmaps.  They are:

    conf.h       - configuration parameters
    gopher.h     - data structure definitions for items and directories
    options.h    - the definition of the application resources structure
    resources.h  - the global definition of the app. resources structure
    globals.h    - a couple of variables, symbolic constants, and macros
    xglobals.h   - shared values defined in the X files
    listP.h      - resources used only in list.c (provided by options.c)
    prefixP.h    - resources used only in util.c (provided by options.c)

    gui.h,  list.h,  misc.h,  net.h,  util.h, help.h,  cso.h,
    index.h, error.h
                 - function declaration headers

Other files:

    README, IMPL_NOTES
		 - documentation files interesting to the installer/programmer
    moog.help    - a sample help file
    moog.man     - a Unix manual page for moog
    moog.ad      - the application defaults file.  It MUST be used!
    Version      - contains the current moog source version number.


Major operating system dependencies have been kept to the file misc.c.
Different versions of Unix may have slightly different programming 
requirements.  These slight variations are handled through
preprocessor directives in the appropriate source files.


Resource Usage
--------------

Considerable effort has been made to maintain and reuse every resource
allocated.  Memory for major data structures is never freed back to the
system, but structures that are no longer in use are maintained and reused
again later.  The idea is that it is expensive to get and build
things, but cheap to reuse them.  This philosophy applies to

  . gopher items (the lines you see on the screen and their selector
    information).

  . gopher directories

  . X window text popups

  . Other popups, panels, and help data.

  . Lists created and used to display the X directory and bookmark
    contents lists.


Gopher Directory Data Structure
-------------------------------

The gopher directories are maintained in a dynamic n-ary tree
as long as each is active.  A directory is active if 

 1) it is the current directory
 2) it is in the bookmark list
 3) it is the ancestor of the current directory or a directory
    in the bookmark list.

Once a directory becomes inactive, the directory data structure
is removed from the tree and moved back to a "free list".

The gopher items associated with a directory are maintained in
a linked list referenced by the directory data structure.  They
are saved (cached) with the directory until either the directory
is released or they become stale.  A time field in the directory
structure identifies the time that the directory contents were
last fetched.  Whenever the contents are needed, the time is
checked, and if some user-specified threshold of elapsed time
is exceeded, then the directory contents are freed and re-requested
from the server.

	Dynamic Directory Tree Node structure (gopherDir)

			        .
			       / \
			        |
			        |
           +-------------+------------+----------+-----------+
           |  markCount  |   parent   |  active  |  sibling +|---->
           +-------------++----------++-----+----+----+------+
      <----|+selectorItem | children | time | content | next+|---->
           +-------------++----------+------+---------+------+
	   | index string|	|                 |
	   +-------------+      |                 +-->
			       \ /                


The list header is used to maintain free lists and the directory
contents list:

	List Header (similar for gopherItemList and gopherDirList)

	  +--------+
	  | first +|--->
	  +--------+
	  | last  +|--->
	  +--------+


Contributors
------------

This version of moog is little more than a Motif port of Xgopher,
hence the credit for the vast majority of the work goes to Allan Tuchman...

"Xgopher version 1.0 was by and large a total rewrite.  It
does however re-use some code and ideas from previous versions.
I cannot determine from older versions who did what, so I want
to credit:

  . jonathan@Think.COM  (apparently responsible for WAIS software)
  . Paul Lindner at University fo Minnesota who wrote the 
    original Xgopher client.

Of course, the present author assumes responsibility for any
problems introduced."





