This file descibes how the Motif server is organized and can be modified.

The files are organized into two source directories:

	/afs/cs/project/clisp/src/alpha/server and lisp.

The server files are the C side. The lisp files are the guts of the CLM like
basis of interaction with Motif. As much as possible of the interaction is
in the lisp side to use the greater power of the language.

Much of the mechanism that makes this possible is in transport.lisp.  No
assumption of reliable transport is made (UDP rather than TCPIP).  Packets
are fixed length 4K groups of bytes which are packed as a sequence to form
messages by the to and from the Motif package.  Packets can be reordered to
correct for transport defects.  There are accessor functions to read and
write from messages from each chunk size of 1,2, or 4 bytes.  The messages
must be aligned on double word boundaries for the MIPS architectures to
avoid nonaligned accessor faults, hence strings are padded to assure
preservation of double word boundaries.  There are also receive and transmit
message functions for transport.  Requests to the server are particular
types of messages.

Internal.lisp handles toolkit errors in a slightly more sophisticated way to
enable the diagnosis of errors without invoking the graphical debugger and
disguising the cause.  Socket handling is in this file to enable connection
to a host.  The central underlying structure is the motif-connection which
contains a file descriptor, the display, and hash tables which map Motif
values to lisp structures.  These hash tables include callbacks, the
protocol employed, and the widget id to and equivalent lisp structure. Also
defined here are motif-objects such as pointers or anything else generated
by the type field (other than widgets), these are things without local state
in lisp. 

In string.lisp *toolkit-string-table* holds the tokenized resource strings
and editable resources by enabling the passing of an index into the table 
rather than the entire string.  Header files are automatically generated in
the build area /motif/server/string-table.h.  Similarly for class-table.h
(the widget classes), interface.h (all requests that can be made of the
server), and TypeTable.h (string name functions for C based write and read
functions and 8 bit type tags).

The file prototypes.lisp contains all requests that can be made by the
server of the interface.  These include things like def-toolkit-request
which takes the name of C based Motif function prefixes it with an R to
form the lisp name and includes parameters to enable confirmation or not 
and a documentation string.  Confirmation is only significant if return values
will be seen, if no values are returned then :no-confirm is sent.  An
example is the manage-child function where no waiting on queued messages is
necessary, hence :no-confirm is returned.  Since the server has not
exhibited any synchronization problems, no gratuitous messages are sent.
Toolkit requests are have argument pairs, normally of the form
	(variable-name LISP-TYPE)
otherwise,
	(resources list kind-of-list)
where the kind-of-list argument is a list of resources(??????).
	resource keyword-name value
The keyword name is the converted name to a string
	((resource-name value)...)

	The C server assumes it is given reasonable data. The Lisp client only
assumes that it's data is not bogus, strings are strings after all.  Type
assertions are made in the LISP client where type enforcement does not carry
the risk of breaking the server. 
	The result type returns an empty list if no value is to be returned,
otherwise up to four values are returned. The results are hard coded(???????)

				SERVER

	The header file functions.h in the Xm subdirectory lists all the 
functions on the C side.  The message parameter returns an integer value.  

	In the tools subdirectory there is a file clm-com.lisp which guides
the recompilation and loading every time a modification is made to the
lisp sources.  Modification to prototypes (???C or Lisp???)
requires the recompilation of all the C macros and header files. Use
clm-com.lisp as a guide for ordering compilation, and target:motif/server to
put header files where you want them for testing, rather than among the
sources. The C side make files are in the build directory in Make. To debug
the C side it will be necessary to replace the -o optimization flag and 
remove the strip command, changing the flag for the PMAX to -g. To debug the
server it is necessary to invoke it with -nofork when using gdb
(TRUE????about gdb) and -debug to generate messages about what it is doing.
(???Verify the location where these flags are applied.)

	All requests are in prototypes.  xt-types.lisp contains all the data
types. Every resource has a "type" string these were set by the Motif
designers.  Lisp doesn't care about the destinction between gadgets and
widgets, except for naming. In def-toolkit-types are alphabetized, that is
presorted for hashing, so this must be preserved when additions are made to
the file.  There are two fields: motif-type and representation, which are
usually the same. In def-toolkit-enum :resize policy can list the entries
for aliases, clm and motif have duplicates, first element is the canonical
value used for return (??????) to assure a kind of pseudo-clm compatability.
If first value is a number skip the holes in the Motif header files.  Most
of the enumerators are in the header files Xm.h