This is the top level directory for the Emu system.
You will need a compiler that understands at least function
prototypes and the void type to compile Emu.

RELEASE NOTES:

The documentation could be more complete. If you still don't know
what is going on after having read the emu.texi file, don't hesitate
to contact us.

HIERARCHY:

The system is broken into several sections, each with its own separate
Imakefile. The Imakefile at the top level (this directory) should be
used to make the emu sample client.

Described briefly, the directory structure is as follows:

    ./canvas		The termCanvas widget
    ./client		Emu sample client code
    ./doc		Documentation
    ./include		Emu system-wide include files
    ./menus		Emu client's configurable menus
    ./misc		Emu system-wide miscellaneous utility routines 
    ./tdesc		Emulator description files
    ./term		The term widget
    ./term/parser	The term widget's parser code.
    ./term/sysdep	The system dependent term code.

Executing "make" in the canvas directory will build a stand-alone test 
program in the event that you have problems.

Doing a make install in tdesc will install the emu defaults in your 
XAppLoadDir and possibly compile a terminfo description for your term type.
You may have to be root to do this.

Also it may be necessary that you install emu itself to be set-uid to
root (i.e owned by root, chmod 4755). This should only be true if 

a) the unuesed ptys on your system cannot be opened, read, written to 
   by anybody.

b) you want utmp handling to work on architectures where it's supported.


VARIOUS QUIRKS AND WHAT'S IN THE WORKS:

Currently, only one canvas is supported for basic VT220 text I/O plus
colored text and double sized fonts. Some enhancements to it are planned, 
including better selection handling, variable font orientation (up-down, 
right-to-left, etc). Unless we get feedback about who would actually
need and want to use these features, we won't implement them.

The communication model between the term and canvas widgets use a
rather "feature" of many current processor architectures, that
sizeof(int) == sizeof(void *). We know, this isn't true and intend
to change it to a more generic approach. Until then you unfortunately
won't be able to run emu on Machines that have 64 bit pointers and
32 bit ints.

Another canvas for supporting basic graphics operations is also
planned, though it may be some time before this is done. If someone
wants to write a basic graphics terminal canvas (and maybe a TEK4014
emulation to go with it), we'll be happy to fold it in.

The term widget itself does not support changing of all of its
parameters once it's realized, though it does allow you to change
things like the current decorations, canvas, read buffer size and any of
the callback functions. If someone can give good reason for changing
some other parameter (like, for instance, the currently executing
command) on the fly, it may be added in. Originally we wanted to
incorporate the capability to change the current emulation - the
hooks are there, it just doesn't work properly yet. So far, we haven't
heard from anybody who would want to have that feature, So we are
a bit in doubt whether it's worth the hassle to have that feature at 
all (E.g. there would be no general way to tell the running shell
that the Emulation has changed and it should change it's TERM
and TERMCAP variables.

The term widget tries to classify all the various system dependent
things one needs to do to launch an interactive terminal emulator
under the 1001 different UNIX mutations currently around, but some
things (like fancy synchronization) will certainly have slipped
through the cracks. If there's some general thing you need to do that
just can't be done within the existing framework, let us know and
we'll try to add a system independent hook to let you do it as cleanly
as possible.  As soon as we get a better idea as to what sorts of
system specific features people _really_ need, we also plan to revamp
the process creation and control system significantly; hopefully to
allow the quirks of different systems to be cleanly isolated.
The emu system is still evolving and all contributions are welcomed.

Likewise, support for systems other than the PCS Cadmus, SUN systems 
running SunOS 4.0, HP/UX, FreeBSD and Linux is rather thin on the ground, 
due to the small number of machines we have available for testing. We will be
happy to incorporate system specific changes (providing that they're
done halfway neatly) if and when they're made available by interested
third parties.

Motif menus are not yet 100% due to the generic approach we've chosen
for the menu interface and probably a lack of understanding of how to
get pop-ups to work with more than one mouse button. In theory a totally
independend menu framework for Motif should be written. If anybody
is willing to help us write one, we'd be only too glad.

We currently support 3 parsers:  A vt220-like parser that, while
fairly close, does not yet support full vt220 functionality (think
of it as a framework in which to add any additional functionality
you may need), an xterm parser that is basically a subset of the vt220
parser (xterm + some extra features), and an "emu" parser which is
basically an artificial terminal engineered to be as efficient to
parse as possible, although it understands some commonly used ansi and
xterm escape sequences such as text color setting and changing the
window and icon title.  This is also the only parser that's available
as a "hard parser" i.e. decoded by C-code instead of through a description
in tdesc. Use the last parser if you're interested in a "lean-n-mean" emu 
that doesn't need to emulate anything existing. Terminfo and termcap
entries are supplied.

The xterm parser is the current default parser.

PORTING:

Porting the Emu system to a new architecture should not be too
difficult, assuming that the user is familiar with tty and process
manipulation on their system. To make things easier, and to avoid
pathological #ifdef'ing of the code, system dependent functions
have been partitioned off into separate files as follows:

term/sysdep/proc_<system>.i		Process handling specifics.
					Conditionally included from
					term/process.c

term/sysdep/tty_<system>.i		Tty handling specifics.
					Conditionally included from
					term/tty.c

For each new architecture, a new set of .i files should be created for
process and tty handling; read term/README for a list of which routines
need to be supported. You may find that one of the existing examples
is enough to get you off the ground with suitable tweaks being made later
as you find problems - look at existing examples for clues.

Certain other system dependant parameters are in include/os.h_tmpl
and may need to be tuned for your system.

General configuration options such as the maximum size of the canvas
and whether to compile in support for double sized fonts are in
include/config.h.

Read canvas/README for a more thorough description about how the double
sized fonts support might need to be tweaked.

If you need to change anything else, let us know. It should have been
system independent, but this isn't to say that it actually *is*, of course.

Next, use xmkmf -a to make Makefiles in the directory tree with your 
appropriate system parameters. 

Cross your fingers and type "make".

Read the documentation and the READMEs in the various subdirectories. They 
describe how to make various parts of the system stand-alone in case of 
trouble. They also describe the generic parser input description format, 
which can look a bit scary if you're not used to it. You may need to 
delve into the actual emulation description if it doesn't do absolutely 
everything you want.

REPORTING BUGS:

Send bugs and/or enhancement requests to the Emu Team (Jordan "term" Hubbard
or Michael "canvas" Elbel):

Email:		emu@pcs.com

Tel:		011-49-89-68004-275 (ask for Michael Elbel).

