created mirror

C++/README

@@ -0,0 +1,5 @@
+C++ version of gzizag
+=====================
+C++ version has been removed from here, because it's not usefull 
+anymore.
+

CODING

@@ -0,0 +1,122 @@
+Coding rules for GZigZag                                        -*- Text -*-
+========================
+	    Tuomas Lukka
+            Antti-Juhani Kaijanaho
+
+$Id: CODING,v 1.18 2001/03/08 15:05:12 tjl Exp $
+
+This document attempts to give a brief guide on how to write
+Java code for this project.
+
+- each Java file should contain the boilerplate copyright and
+  license notice (see e.g. Java/ZZCell.java).
+
+- all of the classes should be in a package. The packages are
+	org.gzigzag            -- general core stuff
+	org.gzigzag.module     -- modules
+	org.gzigzag.dimension  -- dimensions for use with DimSpace
+
+- The main Java/ subdirectory may only depend on the JDK 1.1.8 APIs.
+  Swing is not allowed.
+
+  There is also Java/exp for experimental things that touch the core
+  which may depend on anything but shall not be compiled by default.
+
+  Modules/ can depend on anything, as long as the dependency is documented.
+  Nothing in the main Java/ subdirectory may depend on anything in Modules/
+  This ensures that we retain portability and easy installation. All the user
+  has to do is to give up on a module that has an odd dependency, not the whole 
+  system.
+
+  Note that all modules need not be in the Modules/ subdirectory: for instance,
+  the TextCloud module does not depend on anything beyond the core Java code
+  and may in the future be called by the core Java code so it is located in
+  the core subdirectory.
+
+
+
+- Each class should start with the line (not indented to save space)
+
+public static final String rcsid = "$Id: CODING,v 1.18 2001/03/08 15:05:12 tjl Exp $";
+
+  except interfaces, which should have
+
+String rcsid = "$Id: CODING,v 1.18 2001/03/08 15:05:12 tjl Exp $";
+
+  instead.
+
+  This will pull in the version identifier from the CVS file. 
+  XXX IT SHOULD PROBABLY BE INCLUDED IN THE JAVADOC AS WELL!
+
+- For debugging log messages, use the code
+
+    public static boolean dbg = false;
+    protected static void p(String s) { if(dbg) ZZLogger.log(s); }
+    protected static void pa(String s) { ZZLogger.log(s); }
+
+  to print out messages. The System.out.println() is too verbose to insert
+  into code. This code can be added to the beginning of any class.
+
+  NOTE THE CHANGE FROM PREVIOUS: there is NO "final" qualifier for dbg,
+  as a non-final dbg can be used on the commandline to switch debugging
+  on at runtime, without a recompilation. Not all files have been changed yet.
+
+  NOTE THE CHANGE FROM PREVIOUS: We now use ZZLogger, allowing logging
+  the debug output into a file that can be sent to us in case of a
+  puzzling bug.  This avoids having to have a scrollback buffer in
+  your terminal emulator.
+
+  NOTE THE CHANGE FROM PREVIOUS: there are NO "final" qualifiers for p and pa,
+  because they are unnecessary for static methods. p and pa are now private.
+  Not all files have been changed yet.
+
+  NOTE THE CHANGE FROM PREVIOUS: The methods are now protected; this allows
+  them to be used in subclasses.  When they were private, debugging subclasses
+  was impossible.  Not all files have been changed yet.
+
+- If you want to kill the program, use SafeExit.exit instead of System.exit;
+  this allows consistent cleanup at exit time
+
+- Avoid both under- and overdocumenting.
+
+- Use Java 1.1.8: use of 1.2 features is allowable IF you carefully check
+  that the code works in 1.1.8, minus the features given by 1.2. So for
+  instance, if you make a cache that works with the garbage collector
+  interface in 1.2 to enable passive cleaning, the code should run on 1.1.8,
+  either without the cache, or without the cleaning (currently the ZZCellScroll
+  caches without any cleaning).
+
+  One of the considerations here is that Kaffe JVM provides a completely
+  free platform on which we can run the free GZigZag. If SUN or someone else
+  ever releases their Java implementation under a free license, the situation
+  is completely different.
+
+- Use anonymous classes freely
+
+- Try to keep the external APIs small, *with the exception* of providing
+  convenience routines for classes like ZZCell.
+
+- Indenting: tabstop==8, shiftwidth == 4, cuddled braces, i.e.
+	
+	public void method() {
+	    if(...) {
+		...
+	    } else {
+		...
+	    }
+	}
+
+  however, you may use smaller shiftwidth if the function really really requires
+  it (although you should try to split it up).
+
+- for any more complicated functionality, feel free to start a new
+  "white paper" -type documentation in the Documentation/ subdirectory.
+
+- make your code such that it can be compiled in jikes +P (pedantic),
+  JDK1.1.8 and JDK1.2.2 without warnings or errors.
+
+- as an aside, I really recommend using a coloring editor since there are
+  many points where significant sections have been commented out. This
+  is bad practice but inevitable in a system that doesn't easily allow
+  us to attach the sections which are not useful now but might be later
+  to the text in a xanadu-like manner.

Documentation/ApplitudeWriters/Makefile

@@ -0,0 +1,10 @@
+DIAGRAMS=../wmlinc/article.wml 
+#	rank1vert.png rank2vert.png rank3both.png permascroll.png
+
+all: appw.html appw-ns4.html
+
+appw.html: appw.wml $(DIAGRAMS)
+
+appw-ns4.html: appw.wml $(DIAGRAMS)
+
+include ../lib.mk

Documentation/ApplitudeWriters/appw.wml

@@ -0,0 +1,90 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+   "http://www.w3.org/TR/html4/strict.dtd"> 
+<!--
+	It is written in WML, which is close to HTML while providing 
+	some easier ways to create certain constructions, such as
+	the figure tag.
+
+	NOTE! This file uses WML 2.0.1
+
+	PLEASE PLEASE PLEASE don't edit .HTML. Edit .WML!!!! Actually,
+	it's more important for you since your changes will be LOST FOREVER
+	if you edit the .HTML files.
+ -->
+
+{: [[s/\bZZModule\b/<code>\1<\/code>]]
+
+<html>
+ <head>
+  <title>Applitude Writer's Guide</title>
+
+#include '../wmlinc/article.wml'
+
+
+ </head>
+ <body>
+ <substdims>
+<H1>Applitude Writer's Guide</H1>
+<pre>$Id: appw.wml,v 1.1 2000/08/17 12:56:45 tjl Exp $</pre>
+<grid layout=3x3 spacing=20>
+ <cell> <b>Tuomas Lukka</b> <br>
+ </cell>
+ <cell>
+ </cell>
+ <cell>
+</grid>
+
+<toc>
+
+<warn>
+
+<abstract>
+Applitudes are the preferred way of including more functionality into
+GZigZag. This document explains how they are written.
+</abstract>
+
+
+<h2>Introduction</h2>
+
+	<p>
+	An applitude is basically a view and related actions.
+
+<h2>ZZModule</h2>
+
+	<p>
+	The ZZModule abstract class provides the basic mechanism for
+	including Java code into GZigZag without having to modify and/or 
+	recompile GZigZag. GZigZag uses the Java reflection API to connect
+	to new modules.
+
+	<p>
+	The ZZModule architecture is slightly different than one might
+	expect: instead of directly inheriting from the class, 
+	modules use a static member which is a ZZModule: for example,
+
+<pre>
+public class TextCloud implements ... {
+	...
+	static public ZZModule module = new ZZModule() {
+		public void action(String id, ...) {
+			... execute action id
+		}
+		public ZOb newZOb(String id) {
+			... return a new ZOb instance with the given
+			    name
+		}
+	};
+}
+</pre>
+
+
+ </substdims>
+ </body>
+</html>
+
+:}
+
+<!--
+	vim: set syntax=html :
+-->
+

Documentation/CellScroll/SCRATCH

@@ -0,0 +1,8 @@
+
+
+As a synching method, it is made so that the file is
+4k-aligned, i.e. no records (except those that are longer than 4k by themselves)
+are allowed to cross a 4-k boundary. Zero padding is added to fill 
+the gap. This of course requires that the first byte of a magic no is never
+zero --- then a zero can be interpreted to mean ``jump to the next 4k limit''.
+

Documentation/Clang_Design/Makefile

@@ -0,0 +1,11 @@
+DEP=../wmlinc/article.wml
+
+all thales: thales.html thales-ns4.html
+
+thales.html: thales.wml $(DIAGRAMS) $(DEP)
+
+thales-ns4.html: thales.wml $(DIAGRAMS) $(DEP)
+
+ps: design.ps
+
+include ../lib.mk

Documentation/Clang_Design/design.ptex

@@ -0,0 +1,456 @@
+% BE SURE TO EDIT design.ptex    -*- LaTeX -*-
+\documentclass{article}
+
+\usepackage{rcs}
+\RCS $Date: 2000/08/19 12:16:43 $
+\RCS $Revision: 1.9 $
+\date{Rev.\RCSRevision~~\RCSDate}
+
+\title{Clang Design Document}
+\author{Tuomas J. Lukka\and Antti-Juhani Kaijanaho}
+\begin{document}
+\maketitle
+
+\newcommand{\zz}{ZigZag}
+
+\section{Introduction}
+
+.PS
+box "Clang" ht 0.25
+.PE
+$$\box\graph$$
+
+A cellular language, based on the structure of ZigZag has been in Ted Nelson's
+plans all along. This document attempts to clarify the various issues in
+Clang's design and propose various solutions.
+
+\subsection{The role of Clang}
+
+The exact role of Clang in the various uses of \zz\ is still unclear.
+The \zz\ system will interface to a wide variety of languages (currently 
+Java and Perl), and all these can be used to perform various tasks.
+
+One possible role is as a beginners' language, especially if good visualizations
+and ways to write programs in Clang are devised.
+
+Another possibility is as a kind of device-independent
+virtual machine from which code can be compiled to a faster representation
+or directly interpreted.
+
+A further possibility (one being realized right now (Dec.1999)) is a 
+least-common-denominator scripting language, allowing a simple pure Java 
+implementation of \zz\ for demonstrations as well as practical use, without
+requiring the recipient to set up many libraries and interpreters.
+
+The ability to record macros directly from user input is a great thing.
+
+\subsection{Relevant ZigZag features}
+
+In this section, we shall look at some of the less obvious features
+of \zz\ that might be useful.
+
+\subsubsection{Intersections}
+
+One of the important operations in ZigZag that is quite relevant
+to Clang is the ability to take intersections of ranks.
+As an example, this can be used to find an entry at the intersection
+of a row and column in a traditional 2-dimensional table. 
+Of course, as often is with ZigZag, there is a twist: there may be
+many different intersection points, since the relationships between
+the different ranks are not restricted on a global level.
+
+For most of Clang we are however only interested in single 
+intersection points, e.g. to find the value of a given variable in 
+a give stack frame or the code for a given virtual method in an object.
+
+Eventually, the server should allow requests to store tables
+of intersections so that certain predefined sets of intersections can 
+be found in $O(1)$ time instead of the most general $O(N+M)$ where $N$ 
+and $M$ are the lengths of the two ranks (you get $O(N+M)$ instead of
+the horrible $O(NM)$ through using a hash table).
+However, this is not yet implemented.
+
+\subsubsection{Clones}
+
+Clones are quite an interesting concept. Basically, they are just
+cells that are on a rank on \texttt{d.clone} with the ``original'' as
+the headcell. What is important about clones is the two implications:
+the visual and the semantic. The visual implication is that 
+the rest of the cells will always show the same contents as the
+headcell and all modifications are done to the headcell, not the clones.
+The semantic implication is more important: it says that the clones
+are somehow \emph{same} as the original.
+
+As with the intersection above, clones can be used e.g.~to clone
+method names from an interface to an implementation or something like that.
+
+But now, the important thing to realize about clones is that they
+are special only in these two senses and that we can, if we need 
+(and we will, as you'll see), define other dimensions with similar
+properties.
+
+\section{Global goals}
+
+\subsection{Structure-based referencing}
+
+The most fundamental thing about Clang is that references to various
+structures are structure- and not name-based.  Thus, a variable is
+defined by a cell, which is e.g. cloned along \texttt{d.clone} or some
+other suitable dimension to all the places in a subroutine where it
+occurs.
+
+This makes easy many of the functionalities that the so called
+Integrated Development Environments (IDEs) work very hard to provide
+such as jumping to the definition of a variable or subroutine.
+Also, along with some special rasters the structure allows many
+useful visualizations of the resulting program structure.
+
+The question this change raises, of course, is development speed.
+Will it be significantly slower to write Clang code than corresponding
+Java code? However, some consideration shows this point to be moot: it
+is not at all difficult to come up with suitable macros so that Clang
+can be \emph{written} like a normal name-based language, but where at
+the moment of writing the interpretation to structure takes place.
+
+\subsection{Compilability}
+
+Clang code should be relatively easily compilable into a strongly-typed
+language such as Java in order to gain execution speed.
+
+\subsection{Simplicity}
+
+Ideally, Clang should be simple so that even a beginner is able to write
+simple scripts. 
+
+\subsection{Power}
+
+However, many simple languages lack the power to do complicated things.
+
+\subsection{Self-implementability}
+
+To ensure Clang's power as a general-purpose structural language, it should
+be possible to completely implement a Clang interpreter using Clang itself.
+The only potential problem for this is the dimension along which cell 
+pointers are used (see Cell pointers below). 
+
+
+
+
+
+\section{Interesting ideas}
+
+\subsection{Visible stack}
+
+Stack frames can be represented as sets of clones from the local
+variables (along a different dimension from the cloning to the references
+to the variable in the code). 
+
+Then, the primitive rank-intersection operation in ZigZag can be used
+to find the value of a local variable in a stackframe or thread.
+
+\subsection{Trace}
+
+A trace of executed code can easily be shown on a dimension, with
+relation cells if necessary, along with information about the status
+of data at any point. On the other hand, in a fully versioning ZigZag
+space the whole history of the state of the space is conserved throughout
+the execution (although this may not be wise for complicated scripts 
+where the space overhead would grow too much -- there only the space being
+operated on should be versioned and even that possibly at the beginning
+and the end of a script run).
+
+\subsection{Objects and virtual tables}
+
+It is delightfully simple to do objects and virtual tables using the 
+ZigZag structure.
+
+Quite simply, a virtual interface can be defined simply as a rank of 
+cells and a type implementing them will have the methods' implementations
+start on the intersection of the cell describing the type and the cell
+naming the method.
+
+As an interesting side, since the pointers are bidirectional it is always
+possible to find all the instances of a given class or traverse
+structures both ways, something that 
+programmers in more traditional languages would never dream of.
+Naturally this comes at a some performance penalty but the coherence
+of the structure makes finding bugs in programs far easier.
+
+
+
+
+
+
+
+
+
+\section{Questions}
+
+\subsection{Context}
+
+How much context should the virtual machine have?
+This is an important issue for short scripts
+which should be definable with the minimum effort. 
+Ted says (and I agree) that it should be at least a cursor and three
+dimensions (also as cursors), i.e. a viewspex.
+
+\subsection{Cell pointers}
+
+A variable should in general hold a pointer to a cell (possibly also 
+a direct value
+but this could just as well be implemented as a temporary cell). 
+
+The problem here is clean self-referencing: how can all the cells involved
+in a cell pointer structure be referenced in another cell pointer structure?
+
+SUGGESTION1: "Local" dimensions? This would lead the ZigZag model closer
+to a model of ordered triplets of cells...
+
+SUGGESTION2: Use the same cursor mechanism (the two dimensions \texttt{d.mycursor}
+and \texttt{d.cursor} as the rest of GZigZag).
+
+\subsection{Parameter passing}
+
+\subsection{Expressions}
+
+A rather neat way of doing expressions for parameter passing 
+to primitives and functions:
+the first cell on \texttt{d.1} gives the primitive or function to call.
+Then, on \texttt{d.1} come the parameters - either directly \emph{or} if
+they are connected along \texttt{d.mycursor}, using cursors (global variables)
+\emph{or} if they are connected using \texttt{d.clone} to a parameter cell,
+that parameter. 
+
+However, this is only the beginning: from each parameter, you can 
+start a path down on \texttt{d.2}, which would mean 
+
+\subsection{Exceptions}
+
+
+
+\subsection{Typing}
+
+Typing for Clang is a difficult issue. 
+On the one hand, Perl-like weak typing would suit the ZigZag paradigm
+quite well but on the other hand, compiling a strongly typed program
+into e.g. Java is much easier as well as much more efficient.
+
+SUGGESTION: Have two different languages (Clang and Cling?), one
+strongly and one weakly typed. The one we would first define is 
+the weakly typed one which is generally easier to use for humans.
+
+POSSIBLE IDEA: Dynamically type cell content in Perl style (assign
+dynamically a union of types to a cell based on an analysis of the
+content, for example whether the content string can be parsed as a
+number), but have statically typed cell references.  We'll need here a
+powerful type system (look into type theory, Hindley-Milner typing
+etc), a Java-like type system would probably kill this idea.
+
+\section{Extra-primitive Clang}
+
+XXX This is NOT what is implemented - see the next section!!!!
+
+This section describes the very first steps taken towards
+a cellular language since one is now needed in a hurry to get
+a pure Java implementation of \zz\ out soon (Dec.1999)
+
+This is a testbed-version only and any or all features may be broken
+by further versions. Especially the dimensions may be changed (the first
+version tries to use as few as possible to facilitate viewing on the 
+current primitive rasters).
+This version has no expressions so it is rather like an assembly 
+language instead of a scripting language.
+
+That said, let's begin. 
+
+First of all, we shall have subroutines or procedures.
+They are defined by a cell with the name of the subroutine,
+which has some cells on {\tt d.args} describing the arguments the
+routine requires. The cells on {\tt d.args} will be cloned later
+to refer to the arguments (structural reference).
+NOTE: there is a potential problem here: we also want to be able
+to clone parameter sets for virtual methods and standard routines,
+e.g.~for keybindings). Thus, the cloning dimension may change.
+
+Negwards on {\tt d.args} (later, with better visualizations, on
+{\tt d.retval} or somesuch) are the return values of the subroutine.
+
+The next cell from the main subroutine cell on {\tt d.xeq} is 
+a clone of the cell {\tt VAR}, introducing the local variables just
+like usual languages.
+
+After this, on {\tt d.xeq} the body of the subroutine follows.
+The cell on {\tt d.xeq} is a clone of the operation (or subroutine)
+cell and 
+like above, {\tt d.args} contains the parameters (clones of
+the parameter or variable cells) that are given to the operation,
+and negwards are the return values.
+
+\begin{figure}
+{
+\tt
+.PS
+linewid=0.15;
+lineht=0.15;
+boxwid=0.55;
+SUM: box "sum" ht 0.25; line; DIFF: box "diff" same; line;
+SH: box "sumdiff" same; line; X: box "x" same; line; Y: box "y" same;
+move to SH.s; down; line; box "VAR" same; line; 
+PLUS: box "+" same; line; 
+MINUS: box "-" same;
+move to PLUS.e; right; line; X2: box "x" same ; line; Y2: box "y" same ;
+move to MINUS.e; right; line; X3: box "x" same ; line; Y3: box "y" same ;
+move to PLUS.w; left; line; SUM2: box "sum" same; 
+move to MINUS.w; left; line; DIFF2: box "diff" same; 
+spline from X.s then down 0.1 right 0.1 then down 0.2 left 0.2 to X2.n;
+spline from Y.s then down 0.1 right 0.1 then down 0.2 left 0.2 to Y2.n;
+spline from X2.s then down 0.05 right 0.02 to X3.n;
+spline from Y2.s then down 0.05 right 0.02 to Y3.n;
+spline from SUM.s down 0.1 then right 0.65 down 0.1 to SUM2.n
+spline from DIFF.s down 0.3 then left 0.65 down 0.1 then down 0.4 to DIFF2.n
+.PE
+\box\graph
+}
+\caption{A simple Clang routine {\tt sumdiff} 
+that calculates the sum and difference
+of two numbers by calling the more primitive {\tt +} and {\tt -}
+operations. Horizontally we see {\tt d.args} and vertically {\tt d.xeq}.
+The curvy lines indicate clones along {\tt d.clone}.}
+\end{figure}
+
+The model used to store the parameters is, as alluded to above, difficult,
+as it will be difficult to accommodate the self-referentiality and
+self-implementability.
+For the extra-primitive version, we'll just make do with Clang pointers
+being ordinary relcells. 
+Parameters are passed by value.
+
+\begin{figure}
+{
+\tt
+.PS
+boxht=0.25
+SUM: box "+"; line; X1: box "a"; Y1: box "b";
+move to SUM.s; down; line;
+SUMDIFF: box "sumdiff"; move to last box.e; right;
+line 0.5; X2: box "x"; Y2: box "y"
+move to X1.s ; line to 2/1 of the way between X1.s and X2.s; down; box "Param1";
+move to Y1.s ; line to 2/1 of the way between Y1.s and Y2.s; down; box "Param1";
+.PE
+\box\graph
+}
+\caption{The stack of the virtual machine at the call to the {\tt +} 
+operation. 
+We see vertically {\tt d.stack}, horizontally {\tt d.args}
+and diagonally {\tt d.clangref}.
+Note that the cells {\tt +}, {\tt sumdiff}, {\tt a}, {\tt b}, {\tt x} and 
+{\tt y} are clones of the cells defining the procedures.
+The result cells are not shown, they are referenced the same way
+except through {\tt d.clangretref}, in order to allow passing of 
+variables by reference.
+}
+\end{figure}
+
+
+\section{Clang1}
+
+This section describes the first clang, called Clang1 to distinguish.
+
+The basic concepts are as above: execution down {\tt d.2}, 
+parameters and formal parameters (prototype) on {\tt d.1}, 
+parameters by cloning.
+
+However, there is one important detail which makes programming easier.
+This is the concept of ``it'' which is one cell that is in a special 
+case position. This can later be extended to a stack, if it is felt that
+that is appropriate but that might not be quite as helpful (we do not want
+FORTH, do we?). Now, this concept is there so that it is simple
+to express paths from cells, to be used as expressions. 
+
+Now, all scripts are associated with a viewspecs cell that contains
+at least a cursor and usually some dimensions. 
+The cursor is then equated to the ``it'' so on the main level, moving
+``it'' corresponds to moving the cursor (possibly optimized so that the
+cursor is moved once, at the end of the script).
+
+\begin{figure}
+\caption{
+An expression as a parameter to an operation. 
+The main operation is {\tt Op}, the cell we start from is {\tt v},
+and we use a route that takes us to the cell representing the dimension
+that the view whose maincell is {\tt v} is showing on the Z axis
+(the cursor three steps on {\tt d.dims} from the maincell).
+}
+{\tt
+.PS
+box "Op"; arrow; box "v"; 
+down; move to last box.s;
+arrow; 
+STEP: box "step"; 
+right; move to STEP.e;
+arrow; box "d.dims"; arrow; box "+3";
+.PE
+\box\graph
+}
+\end{figure}
+
+In the first implementation, to make it as fast as possible to implement
+(and to save some space since the current cellscroll does not support
+transient cells), the stack is not stored in the structure. This is
+unfortunate but since no semantics change, it is quite simple to change
+this later.
+
+As some examples, we'll implement some operations here explicitly in
+Fig.~\ref{fig:ops}
+\begin{figure}
+\caption{\label{fig:ops}
+Some operations. a) move poswards on the X axis. b) advance the X dimension
+to the next on the X dimlist. c) One possible alternative, allowing the 
+user to clone "X" only once by expressing the cursor to use negwards on d.1.
+In this case, the {\tt SETC} operation would not be necessary at all.
+}
+{\tt
+.PS
+STEP:box "STEP"; line; box "X"; line; box "+"
+move to STEP.s; line down;
+move to STEP.n; line up;
+.PE
+a)\box\graph\\
+.PS
+STEP: box "SETC"; line; box "X"; line; box "X"; 
+down; move to last box.s; line; box "STEP"; 
+right; move to last box.e; line; box "d.2"; line; box "+"
+move to STEP.s; line down;
+move to STEP.n; line up;
+.PE
+b)\box\graph\\
+.PS
+box "X"; line; STEP:box "STEP"; line; box "d.2"; line; box "+"
+move to STEP.s; line down;
+move to STEP.n; line up;
+.PE
+c)\box\graph
+}
+\end{figure}
+
+\section{Greek Clang}
+
+My (Antti-Juhani's) intention is to build several parallel prototype
+versions of Clang.  Since the version of Clang which will be adopted
+might well use ideas from several orthogonal Clang prototypes, these
+``Greek Clang'' prototypes are not successive versions, improving one
+another, but separate parallel ventures into the design space.  Thus
+they will not be version numbered; instead I'm going to name them
+after ancient Greek philosophers.
+
+\subsection{Thales Clang}
+
+Thales Clang is a small nonstrict, weakly typed procedural-functional
+language with a design in many ways owing to Lisp and nonstrict
+functional languages.
+
+\end{document}
+
+
+%
+% vim: set syntax=tex :

Documentation/Clang_Design/thales.wml

@@ -0,0 +1,187 @@
+# -*- HTML -*-
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+   "http://www.w3.org/TR/html4/strict.dtd"> 
+<!--
+	NOTE! This file uses WML 2.0.1
+
+	PLEASE PLEASE PLEASE don't edit .HTML. Edit .WML!!!! Actually,
+	it's more important for you since your changes will be LOST FOREVER
+	if you edit the .HTML files.
+ -->
+
+# FIXME
+<define-tag zztitle endtag=required>
+  <title>%body</title>
+  <h1>%body</h1>
+</define-tag>
+<define-tag zh2 endtag=required>
+  <h2>%body</h2>
+</define-tag>
+<define-tag zh3 endtag=required>
+  <h3>%body</h3>
+</define-tag>
+
+#include '../wmlinc/article.wml'
+<zztitle>Thales Clang Draft Spec</zztitle>
+<pre>$Id: thales.wml,v 1.4 2000/09/07 12:34:24 ajk Exp $</pre>
+
+<grid layout=3x3 spacing=20>
+ <cell> <b>Antti-Juhani Kaijanaho</b> <br>
+ 	<code>gaia@iki.fi</code><br>
+        Dept. of Mathematical Information Technology <br>
+	University of Jyväskylä 
+ </cell>
+</grid>
+
+
+<p>
+WARNING! This document is <strong>extremely unstable</strong>.  You
+should not depend on any of it to remain as it is.
+</p>
+
+<zh2>Introduction</zh2>
+
+<p>
+
+<zh2>The ZigZag Structure</zh2>
+
+<p>
+
+<p>
+The ZigZag structure consists of cells, cell content and connections
+between cells along dimensions.  Each cell has content (either a
+string or a span), and cells are connected along dimensions.
+Dimensions have unique names.  Dimensions have two directions: the
+positive direction and the negative direction.  A cell may have at
+most one connection along a dimension on a direction.  The term
+<dfn>posward</dfn> means the positive direction and the term
+<dfn>negward</dfn> means the negative direction; in English text they are
+used analoguously to such terms as rightward and upward.  A particular
+instance of the ZigZag structure is called a ZigZag space.
+</p>
+
+<zh2>Cell references in ZigZag: the cursor mechanism</zh2>
+<p>
+
+<zh2>Thales Clang Syntax</zh2>
+
+<p>
+Thales Clang has six syntactic forms: <dfn>cell literals</dfn>,
+<dfn>primitives</dfn>, <dfn>cell denoters</dfn>, <dfn>applications</dfn>,
+<dfn>sequences</dfn> and <dfn>abstractions</dfn>.  Instances of these
+syntactic forms are called <dfn>expressions</dfn>.
+</p>
+
+<p>
+All expressions have an <dfn>identity cell</dfn>, a cell that denotes the
+expression as a whole.  The identity cell of all expression is a
+member of a rank along the dimension d.thales-syntactic-form.
+The headcell of that dimension determines the syntactic form of the
+expression.  An expression can incorporate another expression as a
+subexpression by incorporating in its structure a clone of the
+subexpression's identity cell.
+</p>
+
+<zh3>Cell literals</zh3>
+
+<p>
+A cell literal is a cell that statically represents a cell.  It is its
+own identity cell.  The cell literal refers to the cell in the
+structure that it represents, using the cursor mechanism.
+</p>
+
+<zh3>Primitives</zh3>
+
+<p>
+A primitive is a cell that represents a primitive operation
+implemented outside Thales Clang.  It is its own identity cell.
+</p>
+
+<p>
+Primitive cells are mapped to their implementations using the
+following mechanism.  From the home cell, a rank along
+d.thales-primitives enumerates all known primitives.  Each
+primitive cell is connected posward along
+d.thales-primitive-binding to a cell whose content is a magic
+cookie (a string) used to identify the primitive.
+</p>
+
+<zh3>Cell denoters</zh3>
+
+<p>
+A cell denoter is a cell that dynamically represents a cell.  It is
+its own identity cell.  It is an error for a non-clone cell denoter to
+appear as a subexpression outside the abstraction parameter list (see
+section~<!--\ref{ssec:abstraction}-->).
+</p>
+
+<zh3>Applications</zh3>
+
+<p>
+An application expression is a rank of cells along
+d.thales-application.  The cells in that rank must be identity cells
+or clones of identity cells.  The identity cell of this expression is
+the headcell of the rank.  The headcell of the rank must be a clone of
+the identity cell of either a primitive expression or an abstraction
+expression.
+</p>
+
+<zh3>Sequences</zh3>
+
+<p>
+A sequence expression is a rank of cells along
+d.thales-sequence.  Its identity cell is the headcell of that
+rank, and the rest of the cells must be clones of identity cells of
+identity cells or identity cells of application expressions.  
+</p>
+
+<zh3>Abstractions</zh3><!--\label{ssec:abstraction}-->
+
+<p>
+An abstraction expression is a subspace generated by the expression
+identity cell with respect to the dimensions
+d.thales-sequence and d.thales-application.
+</p>
+
+<p>
+The rank along d.thales-application from the identity cell
+excluding the identity cell itself and the posend cell of the rank
+contains a list of formal parameters for this abstraction.  The posend
+cell of the rank must be an identity cell of another expression, known
+as the <dfn>body</dfn> of the abstraction.
+</p>
+
+<zh2>Informal semantics</zh2>
+
+<p>
+The mechanism by which an application expression whose identity cell
+is a clone of a primitive is evaluated is implementation-defined.
+</p>
+
+<p>
+An application expression whose identity cell is a clone of the
+identity cell of an abstraction is evaluated as follows:
+</p>
+
+<p>
+The subexpression denoted by the headcell of the expression rank is
+evaluated.  The resulting value will be an abstraction.  A fresh
+environment is created with exactly as many positional slots as the
+abstraction value has parameters and one ``inherited environment''
+slot.  The environment captured by the resulting abstraction value is
+bound to the ``inherited environment'' slot of the fresh environment.
+The rest of the cells in the application rank are evaluated in
+negative-to-positive order and the results are bound to the
+corresponding positional slots.  A fresh activation record is created,
+and the fresh environment is bound to its environment slot.  The
+current active activation record is bound to the fresh AR's saved AR
+slot.  The fresh AR is made current active AR.  The body of the
+abstraction is now evaluated.  The AR in the current active AR's saved
+AR slot is made current active AR.  The result of this evaluation is
+the result value of the body.
+</p>
+
+
+<!--
+	vim: set syntax=html :
+-->

Documentation/CyberText/Makefile

@@ -0,0 +1,11 @@
+DIAGRAMS=../wmlinc/article.wml \
+	rank1vert.png rank2vert.png rank3both.png permascroll.png
+
+all: ct.html ct-ns4.html
+
+ct.html: ct.wml $(DIAGRAMS)
+
+ct-ns4.html: ct.wml $(DIAGRAMS)
+
+include ../lib.mk
+

Documentation/CyberText/ct-old.wml

@@ -0,0 +1,911 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+   "http://www.w3.org/TR/html4/strict.dtd"> 
+<!--
+	This is an article intended for the CyberText yearbook.
+
+	It is written in WML, which is close to HTML while providing 
+	some easier ways to create certain constructions, such as
+	the figure tag.
+
+	NOTE! This file uses WML 2.0.1
+
+	PLEASE PLEASE PLEASE don't edit .HTML. Edit .WML!!!! Actually,
+	it's more important for you since your changes will be LOST FOREVER
+	if you edit the .HTML files.
+ -->
+
+<html>
+ <head>
+  <title>GZigZag: a platorm for Hypertext experiments</title>
+
+#include '../wmlinc/article.wml'
+
+
+ </head>
+ <body>
+ <substdims>
+<H1>GZigZag: a platorm for Hypertext experiments</H1>
+<pre>$Id: ct-old.wml,v 1.1 2000/09/13 14:58:08 tjl Exp $</pre>
+<grid layout=3x3 spacing=20>
+ <cell> <b>Tuomas Lukka</b> <br>
+ 	<code>lukka@iki.fi</code><br>
+        Dept. of Mathematical Information Technology <br>
+	University of Jyväskylä 
+ </cell>
+ <cell> <b>Vesa Parkkinen</b>
+ </cell>
+ <cell> <b>Katariina Ervasti</b></cell>
+ <cell colspan=3> and </cell>
+ <cell colspan=3> <b>Ted Nelson</b> </cell>
+</grid>
+
+<toc>
+
+
+<p>
+This is a preprint of an article to appear in the Cybertext Yearbook 2000,
+edited by Markku Eskelinen & Raine Koskimaa, to be published by Research Unit
+for Contemporary Culture.
+All trademarks are the respective trademarks of their owners.
+
+<warn>
+
+<abstract>
+We present a short summary of the ongoing work at the Hyperstructure Group
+in Jyväskylä University. 
+We are interested in structures that currently dominant software 
+paradigm makes difficult
+or impossible to express or edit. 
+For example, current operating systems are fixated on files and directories
+which could be replaced by a much more flexible and more
+fine-grained structural system.
+For many applications it would be useful to keep track of where text
+has been copied from via cut&paste. The current paradigm does not support
+this but e.g. the Xanadu88 paradigm does. 
+Additionally we are interested in useful visualizations of these structures.
+
+Most of our work is based on Nelson's ZigZag
+structure, and we have a prototype program GZigZag on which various 
+variations are tried.
+</abstract>
+
+
+<h2>Introduction</h2>
+
+<p>
+This article attempts to give an overview of the activities of the
+Hyperstructure Group at the University of Jyväskylä.
+The group, founded in fall-99 is focused on a long-term collaboration
+with Ted Nelson and implementing and testing
+his ZigZag design and some Xanadu designs.
+
+<p>
+The most basic idea
+underlying all of our work is that today's computers do not
+allow the user to store and visualize most of the real structure of
+his information.
+An interesting feature of this problem is that it is never visible
+on a small scale, with a few documents or files. On a small scale, the human
+brain is able to superimpose the true structure of the data on the
+structure forced by the computer (filenames and directory hierarchies).
+
+<p>
+Unfortunately, most software is only tested with small amounts
+of example data in the prototype stage.
+If there are hundreds of documents, modified by dozens of people,
+it is easy to fall into chaos unless the true structure of the data
+is used. One simple example of such true structure is that of origination(XXX):
+being able to track all text across several cut&paste operations and
+visualize this makes it simple to see what rearrangements other people
+have done on a piece of text after having seen it last time.
+
+<p>
+Our work is based on Nelson's ZigZag structure XXXREF, introduced below.
+We often use the term ``ZigZag structure''. This is an approximation:
+ZigZag is in a sense a metastructure with which it is easy to model any
+structure, even structures that would be difficult to model on paper 
+or on usual computer programs without a special program designed explicitly
+for that structure - for example a family tree. 
+
+
+<h2>Basics of ZigZag</h2>
+
+<p>
+ZigZag is a new way of putting information into computers, kind of a crossing
+between a database, a filesystem, a personal information manager and 
+many others. And even that isn't sufficient to describe it: it's simply 
+something new.
+There are two important differences between systems built on ZigZag
+and "normal" computer systems.
+
+<p>
+First of all, files and directories are unnecessary (REF paradigms).
+A traditional filesystem uses filenames to refer to large chunks of
+information and possibly HTML-like anchors to refer to smaller pieces
+inside the files. This is a fragile way of representing the information
+since the only <em>structure</em> stored by the system is the files based
+on the names - finding which files reference a given file is timeconsuming
+or requires a pre-indexing scheme.
+ZigZag is a flexible hyperstructure, allowing different micro-level
+connections between various pieces of information.
+In ZigZag all references are two-directional and do not work through
+user-visible namespaces. Rather, the micro-level two-directional 
+referencing is built right into the system. Changing some of
+the connections of a piece of information (e.g. renaming the "file" it
+is inside in the listing) will leave the other connections unchanged.
+
+<p>XXXXX
+Second, in ZigZag, <em>all</em>
+the information about the system will be stored in the same structure.
+In Windows, there is a filesystem and separately from it, there is the
+registry. In UNIX, there is just the filesystem with configuration
+information for applications being represented as text files inside
+the same filesystem; same tools can be used to edit normal text files
+and configuration files.
+ZigZag takes this a step further: all information is in the same fine-grained
+structure instead of the coarse "file-grained" structure.
+The same tools can be used to edit any part of data on the system, be it
+metadata, configuration information, user interface bindings or a spreadsheet
+or document. XXX selitä paremmin
+
+ <h3> Cells and dimensions </h3>
+
+	<figure img="rank1vert.png" width="250px">
+	 Two ranks on <CODE>d.2</CODE>. The rules of the ZZ structure
+	 are that each cell may only be on one rank along a given dimension.
+	</figure>
+
+	<figure img="rank2vert.png" width="250px">
+	 Two different ranks involving some of the same cells, on 
+	 a different dimension <CODE>d.1</CODE>
+	</figure>
+
+	<figure img="rank3both.png" width="250px">
+	 One possible way to flatten the ranks of the two previous
+	 figures to show both dimensions at once. Note how the structure
+	 feels locally spreadsheet-like at each cell but globally
+	 the connections between the cells must curve when flattened
+	 to a 2-D plane.
+	</figure>
+
+	<p>
+ 	In ZigZag, all data is in cells, much like a spreadsheet.
+	The only important difference is that while a spreadsheet enforces
+	a two- (or possibly three-) -dimensional lattice structure
+	between the cells, ZigZag allows the cells to be connected in 
+	a much freer way.
+
+	<p>
+	First of all, the number of dimensions is unlimited.
+	Like on a spreadsheet, a dimension is still structured so that
+	each cell may have one predecessor and one successor on each
+	dimension, and the converse relationship "A is B's successor
+	implies B is A's predecessor" holds.
+	However, there are no restrictions <EM>between</EM> the dimensions
+	for the connections: for example, in the figure,
+	the cell A is located two steps right and three steps up
+	from itself (right = <CODE>d.1</CODE>, down = <CODE>d.2</CODE>).
+
+	<p>
+	To manage the potentially infinite number of dimensions,
+	they are referred to with descriptive strings.
+	The most commonly used dimensions are the three general-purpose
+	dimensions <CODE>d.1</CODE>, 
+	<CODE>d.2</CODE> and <CODE>d.3</CODE> and then <CODE>d.clone</CODE>,
+	used for logical duplication of cells and <CODE>d.cursor</CODE>, used
+	for pointing. These uses are mostly a matter of convention.
+
+	<p>
+	The strength of using dimensions instead of names (as in filenames)
+	or numbers (as in pointers or references) to refer to other
+	information is that all references are two-directional. 
+	This is an important feature since a large fraction of programming
+	errors in languages such as HTML or C++ have to 
+	do with referring to things
+	that are no longer there: on WWW, moving a page or changing the
+	name of an anchor on a page breaks all links to that page or anchor,
+	because the links are strings, naming the previous location.
+	In C++, the references are pointers, i.e. numbers representing
+	memory addresses: if the object being referred to is not any
+	more at the given address, the program crashes.
+	ZigZag introduces the concept of connection
+	on a primitive level and obviates the need for making new systems
+	of referencing for each new program. XXX
+
+	<p>
+	There are many different possible structures with similar
+	capabilities. What makes ZigZag special is the beautiful tradeoff
+	between simplicity and complexity: each cell's neighborhood
+	is limited by the two-neighbours-per-dimension rule but further
+	away the cells can be connected to each other in a free fashion.
+
+ <h3> Rasters and operations: the default UI </h3>
+
+	<p>
+ 	Given the complexity of the structure, it is usually impossible
+	to see it all at once. Focus&context methods (XXXREF) are
+	useful for simple visualizations: two or more dimensions are
+	chosen, and the cells near the user's focus (cursor) are
+	laid flat on the screen using those dimensions, as far as is
+	possible within the limits of the structure. Since the structure
+	locally resembles a spreadsheet, this visualization is extremely
+	navigable, especially with animation between the motions.
+
+	<p>
+	There are several different possibilities for choosing which cells
+	to place where, called rastersXXX.
+	The vanishing raster, for example, renders all cells 
+	up to a given number of steps from the cursor, while 
+	gradually reducing the size of the cells. This gives the user a good
+	picture of what is happening slightly further along in the structure
+	and uses the depth perception cues of the human eye to a great
+	advantage. There are also rasters based on rectangular grids, 
+	with the two most important ones being the vertical and horizontal,
+	which 
+	Examples of these rasters showing a looping structure are shown in 
+	XXX.
+
+	<p>
+	Motion is performed through the keyboard or the mouse.
+	Many simple edit operations take directions as parameters, 
+	so for instance, creating a new cell leftwards from the current
+	cursor is achieved by pressing <KBD>n</KBD> and then the same
+	key that normally moves the cursor left (<KBD>l</KBD>).
+
+
+	<p>
+	The basic operations include connecting and disconnecting cells,
+	moving the cursor, rotating the view (choosing different dimensions
+	to show on the X, Y and Z axes) and modifying the text in a cell.
+	There are also some more complicated operations that are especially
+	useful, such as hop, an example of which is shown in XXX.
+	
+ <h3> Totality of the structure </h3>
+
+	<p>
+ 	Currently, computers are complicated and messy.
+	Application code has to worry about the structure of data on 
+	disk, the structure of data in memory, and the structure of data
+	held by the operating and windowing systems.
+	All these are usually different and cause applications to 
+	translate between each other, making the application overtly 
+	complicated.
+
+	<p>
+	ZigZag represents all this data in the structure: the structure is
+	persistent and unified.
+	Just as with virtual memory, 
+       	the program does not need to care whether a cell
+    	is in memory or on disk. The logical structure
+    	is the same. Of course, to retain an acceptable level of performance,
+	solutions such as transient cells or saving only every <i>n</i> 
+	seconds have to be devised but these are optimizations rather
+	than fundamental structure of the application.
+
+	<p>
+	The unification of the structure is more difficult to explain
+	since it reflects a completely different mindset from the ordinary.
+	Ideally, the lower-level code which takes the structure and renders
+	it on screen will have to know only one cell.
+	From this cell, it uses the structure to find what windows are 
+	where, which cells to show
+	in the centers (via <CODE>d.cursor</CODE>) and which dimensions 
+	to raster along (also via the structure). 
+
+	<p>
+	This greatly simplifies programming in ZigZag since <em>all</em>
+	operations can be expressed as alterations to the structure.
+	For example, when the user presses a key to move the cursor left,
+	what happens is that the callback code looks through the structure
+	to see which dimension is currently "left-right", then looks
+	for the cursor and the cell leftwards of it. Finally, the code
+	connects that cell in the structure so that it will thereafter
+	be interpreted as the cursor.
+
+	<p>
+	There are many other benefits as well: since all operations
+	are in the structure, scripting becomes trivial since everything
+	can be achieved simply through modifying the structure.
+
+	<p>
+	Unification of data is not a new idea: the original
+	UNIX philosophy of "everything is a file" contains some of the same 
+	spirit. However, the UNIX APIs still force the loading of files
+	into memory into a different representation; in ZigZag, the cell
+	structure is all you need.
+
+	<p>
+	Another previous version of the same basic idea is the
+	popular Model-View-Controller paradigm (XXXREF), where a program
+	with a user interface is split into a model and 
+	user interfaces (views and controllers) to that model. 
+	This structure makes it simple to add a new view to the same data.
+	ZigZag takes this approach to new heights by providing a 
+	<em>global</em> model which all features of the visible display
+	use. 
+
+ <h3> Permascrolls </h3>
+
+	<p>
+	Permascrolls are a concept that originated in Xanadu88 (XXX???).
+	The essential idea is that whenever a piece of <DFN>fluid media</DFN>
+	(i.e. text, audio, video, image) enters the system, it is assigned 
+	a permanent identifier. After that, all references to that
+	piece of media go through that identifier so that it is easy to find
+	where a particular piece of text has been cut&pasted to, for example.
+
+	<p>
+	Permascrolls seem to be the most easily misunderstood part of
+	Xanadu88 because with today's web, confusing the physical
+	location and the identity of a document is easy.  A permascroll
+	does <strong>not</strong> mean that all information should only be
+	stored in one place. It is not an URL, but more like an URI: it
+	is an identifier which is known to map to the same information
+	always. It is also more fine-grained than run-of-the-mill W3C
+	URIs, as it allows referencing any subset of the original up to
+	an atomic level.  
+	Most commonly it is not single atoms in the permascroll that
+	are referred to; rather, the reference type is
+	<DFN>span</DFN>, which is a reference to a single contiguous piece
+	of a permascroll.
+
+	<p> XXX SELITÄ VSTREAM HETI
+	In the permascroll paradigm, a particular version
+	of a "document" is represented as a vstream: a list
+	of spans. Editing a document then consists of adding a new
+	span, splitting existing spans, deleting existing spans and
+	rearranging spans.
+
+	<figure img="permascroll.png" width="250px">
+		Two different versions of a document using vstreams
+		and permascrolls. The second version is produced from the 
+		first by a rearrangement and an insertion.
+		When comparing the two versions side by side, it is
+		easy to determine 
+		which parts are the same and simply have been rearranged
+		by comparing the references to the permascroll.
+	</figure>
+
+	<p>
+	ZigZag supports permascolls by allowing a cell to contain 
+	a <DFN>span</DFN> (a reference to a single 
+	contiguous piece of the permascroll).
+	A rank of cells on a dimension (usually <CODE>d.2</CODE>)
+	can then be interpreted
+	(see next section) as a virtual text (or other media) stream.
+
+	<p>
+	To reiterate, a permascroll is not a place:
+	it is a state of mind, in which you keep track of what all
+	information copied or cut&pasted originally was. 
+	For example, it is planned that in a future version of GZigZag
+	the user will be able to send an email with some cells
+	as well as the parts of the permascroll that is referred to
+	by those cells. The recipient's computer can then
+	store those pieces of the permascroll and notice if any other
+	references to them exist.
+	In fact, permascrolls are excellent candidates for caching since
+	the identifiers to the content are indeed permanent, unlike
+	on WWW where the content of a cached URL can change at any time.
+
+
+	<p>
+	Another application where permascrolls show their power is
+	comparison: most utilities used for text comparison (e.g. the
+	unix <CODE>diff</CODE> utility) do a reasonably good job if the
+	user is simply adding or removing or changing small pieces of
+	text. However, such tools have great troubles with rearrangement,
+	exactly because of the lacking text model where only the content,
+	not the origin is stored. Thus, a rearrangement usually shows
+	up as large insertions and deletions, which is actually exactly
+	what it is, in the primitive text model.
+
+	<p>
+	It is possible to overcome some of this problem by writing
+	more and more refined algorithms for finding similar texts but
+	once we get to phrase-level elements, they become useless since
+	the same phrases can occur again and again in a document.
+
+	<p>
+	With permascrolls, rearranging a text file is not about moving
+	the text content - it's about moving <em>pointers</em> to the
+	content. So two different revisions, the latter of which has
+	been rearranged, still point to the same spans of text in the
+	permascroll. Now, visualizing the differences becomes easy:
+	all that is necessary is to point out to the user which pieces
+	of text are stored in the same place in the permascroll.
+	See Figure XXX below, where this is demonstrated.
+
+	<p>
+	This feature may seem like unimportant but in projects with more
+	than one worker and much rearrangement of the manuscript
+	it can be truly invaluable for finding where a certain part of the
+	previous version of the manuscript ended up.
+
+ <h3> Alternative visualizations: applitudes </h3>
+
+	<p>
+ 	Although interesting, the above structure and visualizations
+	would fit most applications rather poorly. However, given the
+	basic ZZ structure it is simple to define new visualizations.
+
+	<p>
+	Taken together, a visualization and operations are referred
+	to as an <dfn>applitude</dfn>, 
+	as opposed to the traditional term application
+	since all the data is still in the same structure and other
+	operations can be used to edit this data and these operations
+	can be used to edit other data.
+
+	<p>
+	For example, a vstream is a kind of an applitude: there is a 
+	clearly defined internal structure and special operations for
+	the vstream for inserting and deleting characters.
+	There is also a good visualization of a text vstream: simply
+	the characters in a paragraph (formatting capabilities will
+	be added later).
+	The default cell-based visualization and the natural vstream
+	visualization for a small piece of text is shown in XXX.
+	Note how the colored cursor is shown in both panes.
+
+	<p>
+	The interesting thing about applitudes is that they can be designed
+	to be connected to each other in a more fine-grained fashion than
+	current embedding frameworks such as Bonobo, KParts, or OLE/COM.
+
+
+
+
+<h2>Some Textual Applitudes of ZigZag</h2>
+
+<p>
+In this section, we'll look at some functioning applitudes.
+As explained in the previous section, the strength of ZigZag lies in that
+all these applitudes can be used together fairly easily since all the data
+is stored openly in the ZZ structure.
+
+<p>
+One important function that GZigZag provides for all applitudes is
+<em>animation</em>. This works by associating a cell with all "things"
+that are rendered on the screen.
+When two "things" in subsequent keyframes (i.e. the fully rastered frames)
+are associated with each other, the system generates as many interpolated
+frames between them as the speed of the host machine allows. 
+The time between keyframes is estimated from the interval between 
+the user's keystrokes: the system attempts to be ready 100ms before
+the user strikes the next key. This gives the system a fluid, responsive
+feel while allowing smooth, slow animation if the user is moving slower.
+
+<p>
+An example of such animation can be found in XXX ANIMATED GIF ON 
+GZIGZAG PAGES
+
+ <h3>Text cloud - <strong>real</strong> cut&paste</h3>
+ 	
+	<p>
+	One of the points Nelson has made in several talks (XXX??? on paper?)
+	is that the term "cut&paste", as used in the computer field, is
+	a really bad choice of words. Originally cut&paste meant physically
+	cutting a text into pieces, rearranging the pieces and glueing 
+	them together. This seems a little similar to what the computers
+	do. 
+
+	<p>
+	However, there is a crucial difference: in physical cut&paste,
+	the text can be cut up into as many pieces as desired; 
+	all the pieces are visible all the time; the pieces can be slowly
+	rearranged into the optimum order in a parallel fashion.
+	Indeed, when the text is cut up, the actual <em>data model</em> 
+	of the text
+	is changed from the single text stream to a cloud of text 
+	fragments.
+
+	<p>
+	Most current computer programs (XXX Exceptions?) force the user
+	to stay within the formal one-stream text model all the time during
+	editing, except for a single piece of text cut onto the "clipboard",
+	which is not seen.
+	This is why several people (REF: private communication) seem
+	to use a second window next to the main one to hold fragments.
+	This, of course, has several disadvantages: the fragments are
+	stored separately from the main body of text, the fragments still
+	have to be stored in the one-stream text model and the system is
+	rather clumsy. Of course, some people are able to write near-perfect
+	prose in near-perfect order.
+
+	<p>
+	One of the interesting differences between this system
+	and the dominant paradigm is the way of selecting text.
+	In most current systems, selecting text is performed by
+	painting, i.e. pressing the mouse button at one end of the
+	span being selected and releasing the mouse button at
+	the other end. In the TextCloud demo, text is never really
+	"selected" in the same way: instead, the user can make any
+	number of <dfn>cuts</dfn> into the document using the right
+	mouse button. Then, when the user presses the left mouse button 
+	on some text and drags, the text is separated at the neighbouring
+	cuts to allow the user move a single piece of text.
+
+	<p>
+	Already Nelson's original mockup pictures about Xanadu 
+	(see XXX (pic on WWW)) 
+	include transpointing windows, i.e. windows which show the 
+	connections of their respective contents graphically.
+	These connections can be either transclusions or links. In this
+	article, we concentrate on transclusions.
+
+	<p>
+	GZigZag is probably (XXX???) the first system to implement such
+	transpointing with beams: an earlier Xanadu client Pyxi by XXX
+	shows transclusions by colors but does not do transpointing.
+	The TextCloud applitude is a good place to see the transpointing beams
+	in action: simply copying (i.e. dragging with Shift-MouseButton1 instead
+	of just MouseButton1) a vstream creates a transclusion and the
+	beam appears. Then, when editing one (or both) of the streams by 
+	cutting&pasting text the beams remain 
+	connected; this is because the beams are really connected to the actual
+	text content, not just the external object.
+
+	<p>
+	The TextCloud is a simple model and its current implementation clear 
+	limitations: all text must be stored in this one area and the size
+	of the text cannot be changed. 
+	Also, it does not interface well with the other parts of the system.
+	It is simply one step on the way towards the full system, in order
+	to test one user interface aspect of it.
+
+
+ <h3>Editing longer documents using cells</h3>
+
+	<p>
+	A different way for editing longer documents is through putting
+	vstream fragments of the documents in ZZ cells which are then rendered
+	in a raster. All the structural capabilities of ZigZag are
+	then in use for rearranging the pieces.
+
+	<p>
+	This being ZigZag, note that "putting fragments in ZZ cells"
+	does not a literal inclusion but an <i>interpreted inclusion</i>:
+	the view has a special raster which knows how to look for
+	the vstream to include in a cell.
+	When the space is being rastered, 
+
+	<p>
+	Unfortunately this demo is not yet finished so we cannot offer
+	a screenshot.
+
+ <h3>Hypertext without lexias (XXX?)</h3>
+
+ 	<p>
+	Hypertext has come to mean "WWW-like" in many places:
+	a paradigm where the user is presented with one lexiXXX,
+	performs a selection, for example clicking with the mouse,
+	and is taken to another lexiXXX.
+
+	<p>
+	GZigZag makes it possible to easily create a wealth of flexible
+	visualizations that do not use such fixed screenfuls of text.
+	This is because GZigZag is built in a modular fashion and makes
+	it easy to describe a new visualization.
+
+	<p>
+	For example, let's start with a text model that contains 
+	simply paragraphs of text, one after another.
+
+
+ <h3>Email or forums with coordinates</h3>
+
+	<p>
+ 	In this section, we come once again to a problem which 
+	does not exist for small data sets. If there are
+	only 10 messages in 
+	a mailbox, it does not matter in the least how incredibly
+	bad the mail reading program is: 
+	humans can still manage since they can remember
+	and overlay the true structure on top of the rigid and unnatural
+	structure imposed
+	by the mail reader program.
+
+	<p>
+	However, consider the linux-kernel email list or
+	corresponding high-volume newsgroups on the usenet. 
+	Most programs for reading news or email are based on the assumption
+	that the reader wants to read all or most of the incoming messages -
+	a natural assumption stemming from the original volume of the forums.
+	However, with time the number of messages in a forum has grown
+	unmanageably yet programs mostly offer only rigid pre-selection systems
+	such as killfiles which remove all messages with a given subject 
+	or sender from the view.
+
+
+	<p>
+	ZigZag and FloatingWorld provide an interesting alternative
+	which we have so far had time to only scratch the surface of.
+	When a mailbox or a newsgroup is incorporated into the structure
+	correctly, it is simple to write interesting visualizations
+	that show some of the emails.
+
+	<p>
+	The structure underlying the email applitude is described in 
+	FIGUREXXX.
+	
+	<p>
+	The first, simplest visualization FIGUREXXX
+	is simply the traditional 
+	mailbox visualization, offered by many programs such as Pine, XXX.
+	This simply shows some of the most relevant header fields of
+	messages on each line, arranged vertically in the mailbox order.
+	Already here ZigZag has several tricks up its sleeve. For example,
+	a message may be stored in several "folders" (lists), either
+	by using different dimensions for different folders or by
+	cloning the headcell of the
+	message onto different ranks on the same dimension.
+	Another trick here is that it is easy to see which folders
+	a given message has been connected to, since all connections are
+	two-directional. This is an advantage caused by the fact that ZZ
+	considers the message to be an entity rather than a stream of 
+	characters that can be copied but has no <em>identity</em> 
+	(like emails in normal email folder files).
+	
+	<p>
+	Sorting the emails is of course possible, either by presorting
+	and making a rank of them and using that
+	or by post-sorting at each time they are shown.
+	For sorting, ZZ offers an interesting user interface: when the
+	user moves the active cell <em>horizontally</em>, the list of
+	mails is shown sorted according to that cell.
+	XXX Mailboxes, many folders per email!!!!!
+	XXX Good argument for postsorting or cached postsorting.
+	XXX Notifications
+
+	<p>
+	
+	<p>
+	Now, one interesting thing that ZZ offers is multiple windows
+	with different views whose cursors are bound together (using
+	the cursor-cargo mechanism; see the ZZ Spec XXXREF).
+	All the views above have one "active" cell. We can have several
+	useful views visible at the same time, which stay in lockstep with
+	each other.
+	
+
+	
+	<p>
+	The FloatingWorld model offers an alternative: messages
+	or icons of messages can be shown in a two- or three-dimensional
+	coordinate system. 
+
+	<p>
+	Such a system is trivial to implement in a general fashion
+	using ZigZag since the homogeneous structure makes it simple
+	to specify paths to obtain coordinates through, whereas if 
+	using a traditional programming language, it would be all too easy
+	to restrict the world of possible coordinates to some set
+	that is easily specifiable in the structure that was chosen.
+
+	<p>
+	Additionally, normal email programs or HyperMail (XXXREF) 
+	-like HTML indexers treat the messages as their own, making it
+	almost impossible to link the discussions into the places where
+	they would belong: for example, linking the discussion leading up
+	to a particular decision in a standard (say XHTML) into the place
+	in the standard would be an invaluable aid to those trying to
+	understand afterwards how something is supposed to work.
+
+	<p>
+	Consider, for instance, a document such as the Kernel Traffic
+	weekly newsletter (XXXREF) which summarizes the main discussion threads
+	on the Linux-Kernel mailing list that week. 
+
+	XXX transclusions, etc.
+
+ <h3>Editing hyperliterature with nodes</h3>
+	<p>
+	- editing trad. hyperliterature easier: visualize the STRUCTURE of
+	  the whole work, then rendered into HTML
+
+ <h3>Scientific publishing using Xanadu hypertext</h3>
+
+	<p>
+	A long-known problem in scientific publishing on paper media is
+	that bibliographic references are always backwards in time, while
+	it would often be more interesting for the reader to
+	know the future references, i.e. either articles that refer
+	to the current one or articles that the author has deemed
+	interesting enough to refer to at a later date from publication.
+
+	<p>
+	Now, in the Xanadu model, quoting is equivalent to linking because
+	of transclusions. 
+
+	<p>
+	Transclusions may seem foreign as an instrument of quoting and
+	responding to a selected portion of an article. However, they
+	are actually quite close to another widely used paradigm: quoting
+	when replying to an email. The only addition here is that 
+	the quoted parts (which are somehow visually indicated) are 
+	not copies but transclusions from the original article. Because of
+	this, they are actively connected to the originals in an implicit
+	two-way link.
+
+	<p>
+	The system of moderation used on sites such as <code>slashdot.org</code>
+	is surprisingly similar to the scientific refereeing process.
+	The privilege of moderating other users' comments is granted
+	to established members of the community (members whose previous
+	moderations have been approved by other members), the process
+	is anonymous and determines on whether users get to see the comment.
+	However, there are important differences:
+	<ul>
+	 <li> The moderation is not "accept/reject" but rather
+	      "leave as is/ increase score/ decrease score".
+	 <li> Comments are not deleted even if they have a low score;
+	      users browsing the site can set their comment limit
+	      themselves to determine what minimum rating for comments
+	      they wish to see.
+	 <li> A user has a default score based on his/her earlier
+	      success in posting comments
+	 <li> Comments are usually short notices on 
+	</ul>
+	Upon consideration, some of these points are quite applicable
+	to scientific publishing as well. Specifically, the "letters
+	to the editor" section of scientific journals seems to be the 
+	closest that print journals can come to this kind of convenience.
+
+	<p> 
+	Indeed, this sort of publishing system could create a far more
+	interactive scientific <em>discourse</em>.
+	For example, a user can choose which links he wishes to see
+	when reading an article: refereed links, all links, links by certain 
+	persons etc.
+
+
+
+
+<h2>The Code</h2>
+
+<p>
+GZigZag, which is the program that is shown in all of the screenshots
+in this article, is free software. It is distributed under the FSF's
+Lesser General Public License (LGPL) and is available on SourceForge.
+
+In the language of the free software community, "Patches accepted".
+
+<h2>Conclusions</h2>
+<p>
+
+<h2>Acknowledgements</h2>
+<p>
+
+<h2>References</h2>
+<p>
+http://www.acm.org/cacm/AUG96/antimac.htm
+
+<h2>Glossary</h2>
+
+<p>
+This article uses many terms that are most likely unfamiliar to the reader.
+We attempt to summarize the most important ones below.
+
+<hr>
+<dl>
+	<dt>ZigZag structure / space
+	<dd>	A simple structure, based on <i>cells</i> and <i>dimensions</i>
+		which the user is able to easily shape into any desired
+		structure. All interrelated pieces of information can be
+		close to each other on some dimension.
+	<dt>cell
+	<dd>	The smallest unit of information in ZigZag.
+		A cell can contain a text string or 
+		a single span in a permascroll; the separation is
+		because a text string can be edited but a span can only
+		be lengthened or shortened: no characters can be 
+		inserted. Cells are connected to each other along
+		dimensions.
+	<dt>dimension
+	<dd>	Connecting cells along dimensions is what ZigZag is
+		about. Locally, dimensions work just like on a spreadsheet:
+		each cell can be connected to one cell in the positive
+		direction and to one cell in the negative direction 
+		along each dimension. However, there are no global constraints
+		between the dimensions.
+		
+	<dt>rank
+	<dd>	A rank on a dimension D is simply a set of cells that are
+		connected to each other on D. A given cell can only
+		be on one rank on a given dimension.
+
+	<dt>raster
+	<dd>	A simple visualization of the ZZ structure.
+		A raster is given a cell to place in the center of
+		the view and a set of dimensions chosen for the coordinate
+		axes X, Y and possibly Z, and it starts at the center cell
+		and places other cells on the screen according to simple
+		rules.
+		There are several different rasters.
+</dl>
+<hr>
+<dl>
+
+	<dt>FloatingWorld
+	<dd>	Ted Nelson's design built on top of ZigZag structure,
+		based on <i>flobs</i>.
+	<dt>flob
+	<dd>	A multi-dimensional flying object. That is, an entity
+		representing something that may have any number of 
+		<i>flob coordinates</i>. For example, an email's sender is one
+		flob coordinate, its subject another.
+
+</dl>
+<hr>
+<dl>
+
+
+	<dt>Xanadu88
+	<dd>	A hypertext system, finished in 1988, which works by
+		stable <i>fluid media</i> content instead of URL-like pointers.
+	<dt>fluid media
+	<dd>	Any media types that can be subdivided.
+		Text, audio, video, images.
+	<dt>permascroll
+	<dd>	A storage philosophy for fluid media where
+		each smallest unit (e.g. character of text)
+		is assigned a permanent identifier when
+		it first enters the system. Of course, 
+		references to the smallest units usually happen
+		through <i>span</i>s for efficiency.
+	<dt>span
+	<dd>	A (reference to a) contiguous section of the permascroll.
+	<dt>vstream
+	<dd>	A list of spans that describe a virtual stream of
+	    	fluid media. A "document" or one version of a document.
+		Modifying a document does not modify the permascroll, except
+		by appending new inserted characters. Instead, the spans
+		of the vstream are modified: split apart, new spans
+		inserted etc.
+	<dt>transclusion
+	<dd>	The inclusion of the same material in a permascroll in 
+	    	two different documents. One of the fundamentals of the Xanadu88
+		model is that it is efficient to search for transclusions
+		of a given span.
+	<dt>transpointing windows
+	<dd>	Windows on a computer screen that show the connections or 
+		transclusions between each other.
+
+</dl>
+
+<h2>SCRATCH</h2>
+
+<p>
+<b>
+This section contains rejected pieces of text that may still
+have some interest.</b>
+
+	<p>
+	Naturally, if desired, dimensions can be used to construct
+	systems analogous to files and directories: for instance,
+	a number of cells going down <code>d.2</code> can contain names
+	and these cells are connected on some dimension to the content
+	for that "file".
+
+	<p>
+	This is somewhat analogous 
+	to the hyperbolic visualization
+	for graphs (XXXREF): hyperbolic space also looks locally like 
+	Euclidean space but there is more "room" because the correspondence
+	to Euclidean space does not hold over distances.
+	An interesting similarity between the two is the volume of balls: 
+	in hyperbolic space, the volume enclosed in a ball grows exponentially
+	with the radius and the same is true for ZigZag - <em>if</em> 
+	desired; ZigZag cells can also be arranged in a less complex 
+	fashion where the growth of the volume of balls is more restricted.
+
+<hr>
+ </substdims>
+ </body>
+</html>
+
+<!--
+	vim: set syntax=html :
+-->
+

Documentation/CyberText/ct.wml

@@ -0,0 +1,275 @@
+<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
+<html>
+<head>
+<title>GZigZag - A Platform for Cybertext Experiments</title>
+<meta name="keywords" content="GZigZag, ZigZag, Ted Nelson">
+</head>
+<body bgcolor="#ffffff" link="#cc0033" vlink="#888888" alink=
+"#ffffff">
+<blockquote>
+<p>
+<i>GZigZag - A Platform for Cybertext Experiments</i><br>
+Tuomas Lukka & Katariina Ervasti
+</p>
+
+<p>ABSTRACT</p>
+
+<p>This article describes GZigZag, which is currently the main project of the Hyperstructure Group 
+at the univ. of Jyv&auml;skyl&auml;. GZigZag is an implemention of ZigZag, a computer paradigm invented 
+by Ted Nelson. The paradigm abandons many currently central concepts, such as folders, files and 
+applications, and instead offers a more flexible way to arrange information. Already at this early stage 
+of development GZigZag has advantages compared with other computer systems.</p>
+
+<p>1. INTRODUCTION</p>
+
+<p>"COMPUTERS ARE FUNDAMENTALLY BROKEN" lectures Ted Nelson (7 February 2000). Unlike 
+many other critics, he also offers ideas for improving the situation. Some of his ideas are 
+currently being implemented by the Hyperstructure Group at the university of Jyv&auml;skyl&auml;, Finland. 
+In this article we present a short summary of our ongoing work.</p>
+
+<p>1.1 Defamiliarization of files, folders and applications</p>
+
+<p>Nelson (1999a) offers many reasons for why users face difficulties with present PCs. This article 
+only includes a short attempt to defamiliarize (<a href="#1">1</a>) folders, applications and files from the user's point of view. 
+This is not an easy task, because folders, applications and files are one of the first things a beginner 
+is taught and are not often questioned.</p>
+
+<p>Hierarchical directories, also referred to as 'folders', were invented to help finding the right file 
+among many files (Nelson 1999a). Let us say that in September -99 a writer has been writing an 
+article dealing with the impossible nature of her cat Vilma.  In September 2000 she wants to find the 
+article again to edit it for a new purpose. In order to find the article, she opens a folder named 'Vilma'. 
+The folder includes approximately twenty files, which are either versions of the final article or include 
+some ideas the writer has considered worth writing down at some point of the writing process. The 
+files have names such as <i>vilma3.doc</i>, <i>vilma4.doc</i>, <i>vilfoo.doc</i> and <i>vilmaprob.doc</i>. By the time the 
+writer finished the article she had no time to make an index explaining the contents of each file. Finally, 
+after opening and closing several files, she succeeds in finding the right file and starts working. When 
+editing, she suddenly remembers that she had a slightly different version of a paragraph in another 
+document. Once again, she has to start opening and closing files to find the right file.</p>
+
+<p>Applications, then, are used for performing different tasks with the computer (Nelson 1999a). Problems 
+arise when a user wants to use the same information in many applications. For example, a multimedia 
+author, who has manipulated sound with SoundEdit, might want to use the sound in a multimedia 
+presentation made with Macromedia Director. Since applications do not support all file formats, 
+he has to find out which sound file formats Macromedia Director supports. After a study of sound 
+file formats, he saves the file in a suitable format and imports it to Macromedia Director. Then, if he 
+later views the presentation and wants to find a different sound sample, which he remembers recording 
+in the same session, it will not be easy. This is because there is simply no connection between 
+the Macromedia Director file and the original sound sample nor between the original sound sample 
+and the second sample from the same session.</p>
+
+<p>These examples demonstrate how the files and folders model of storing information is insufficient: 
+it does not allow the users to track the conceptual relationships between related information or 
+versions. Files, folders and applications are easy to understand but do not need to be, as 
+Nelson (lecture, 30 August 2000) explains, fundamental concepts of software. The above 
+problems could be solved by designing software differently, starting from different assumptions.</p>
+ 
+<p>1.2 Traditions of Bush and Engelbart</p>
+
+<p>Vannevar Bush and Douglas Engelbart developed ideas for tools that would improve the 
+working conditions of people who perform complicated tasks in the complicated world. Bush, who 
+had noticed the explosion of information already in the 1940's, is famous for proposing <i>Memex</i>, 
+a "mechanized private file and library" designed to help individual scientists store and handle the 
+growing amounts of information needed in their work (Bush 1945). Engelbart, the developer of NLS, 
+a tool for collaborative work, writes about augmentation of man's intellect, which has been the goal 
+of his work with computers. By augmenting man's intellect he means "increasing the capability 
+of a man to approach a complex problem situation, gain comprehension to suit his particular 
+needs and to derive solutions to problems" (Engelbart 1962). The purpose of our work is similar 
+to Bush's and Engelbart's: we want to facilitate the production and arrangement of information 
+by creating, as Nelson (1999b) expresses it, "a high-power personal and media system, with editing 
+and presentation systems that expand the state of art".</p>
+
+<p>2. BASICS OF ZIGZAG</p>
+
+<p>Defining ZigZag is difficult, because ZigZag is so different from any software in the currently 
+dominant computer paradigm. It is not an application but neither is it an operating system or 
+a platform. It is a new way of putting information into computers, a cross between a database, 
+a filesystem, a personal information manager and many others, and even that is not sufficient 
+to describe it. ZigZag is simply something new and different.</p> 
+
+<p>3.1.1 Cells, Dimensions, Views and Applitudes</p>
+
+<p>A ZigZag structure consists of cells and dimensions. A <b>cell</b> is the basic unit of information 
+in ZigZag. A cell can contain an information unit of any kind, for example text (e.g. "Vilma"), an 
+image (e.g. a picture of Vilma) or sound (e.g. "Meow" by Vilma). Cells can be connected with 
+each other along <b>dimensions</b>, which are referred to with names such as <i>d.1</i> or <i>d.cursor</i>. On 
+each dimension, each cell can have two neighbours: a predecessor and a successor. The number 
+of dimensions is not restricted, and it is easy to create new dimensions. For example, if Ville wants 
+to comment on many different cells, he could use <i>d.Ville-comment</i> for connecting his comments 
+to the cells.</p>
+
+<p>Figure 1 shows a simple structure. In the Figure, cells are represented by rectangles and neighbours 
+along a dimension by a line.</p>			
+
+<p><a href="vilma.png">Figure 1</a>.<i>Seven cells, connected to each other along the two dimensions d.1 and d.2</i></p>
+
+<p>There are several different visualizations (views) of the ZigZag structure. The views range from 
+<b>general view</b>s that are useful for looking at all kinds of structures to <b>specific view</b>s 
+that are useful for only one particular kind of structure. For example, Fig. 2 shows a generic view of a structure 
+that represents a schedule of a day. This view can show any kind of structure in a fairly reasonable 
+way, by showing the cells arranged along the dimensions and their text contents.</p>
+
+<p><a href="kello.png">Figure 2</a>.<i>The most important events of a day in a general view</i></p>
+
+<p>Figure 3, then, shows a specific view of the same structure. The underlying data is exactly the 
+same, but the specific view designed especially for the purpose interprets the structure and draws 
+the events in a more visual manner. Looking at another structure through this view would not make 
+sense because the view is designed especially for this structure.</p>
+
+<p><a href="kello-o.png">Figure 3</a>.<i>The same events in a specific view</i></p>
+
+<p>Combining the specific view such as the schedule view above with special operations for editing 
+such a structure, for example dragging the start and end times with the mouse makes an applitude. 
+Thus, an <b>applitude</b> consists of views and operations designed for a particular purpose. Even though 
+the term 'applitude' resembles the term 'application', there is an important difference: in ZigZag 
+nothing is separate, and applitudes, unlike applications, can be combined with each other, as the 
+example of the next section shows.</p>
+
+<p>3.1.2 Example: Address Book and Family Tree in GZigZag</p>
+
+<p>One of the first examples Nelson (pers.com., 25 August 2000) has used to demonstrate 
+ZigZag is the <i>Holm Family Demo</i>, a family tree prepared for his talk at the University of Oslo 
+to show how he is related to one of the professors of the university. Here, a variant of Nelson's 
+original example is used, combined with an address book.</p>
+
+<p>The structure of the address book is simple: it is a list of names and addresses . The names are 
+listed along <i>d.2</i> in alphabetical order. The addresses are connected to the names along <i>d.1</i>. 
+Figure 4 shows the (incomplete) address book in the row view.</p>
+
+<p><a href="1.png">Figure 4</a>. <i>The address book in the row view</i>.</p>
+
+<p>Since the list of relatives is long, only a subset of it can be seen on the screen at a time. In Figure 4 
+the cursor is on the cell 'cousin 1'. Moving the cursor down would cause more cells below 
+the 'grandfather 2' cell on <i>d.2</i> to become visible.</p> 
+
+<p>Next, the address book is combined with the family tree, which is represented by a slightly more 
+complicated structure, shown in Figure 3.</p> 
+
+<p><a href="3.png">Figure 5</a>. <i>One family of the family tree in the row view</i></p>
+
+<p>The two dimensions <i>d.marriage</i> and <i>d.children</i> are used to represent the family tree. Siblings 
+are connected along <i>d.children</i>, and married couples along <i>d.marriage</i> (<a href="#2">2</a>). An extra cell ("+") is used 
+on <i>d.marriage</i> to make the structure symmetric, and the list of children from the marriage on 
+<i>d.children</i> starts from that cell. Figures 5 and 6 show two different views of the structure. 
+The row view, as Figure 5 shows, enables dealing with one family at a time. The vanishing 
+view shown in Figure 6 gives a better picture of the family tree as a whole.</p>
+
+<p><a href="4.png">Figure 6</a>. <i>The family tree in the vanishing view</i>
+
+<p>It is important to realize that the same cells are used to represent the relatives in both the 
+address book and the family tree, and that the connections related to the two applitudes are 
+along different dimensions. In the default views only two or three dimensions (x,y,z) can be 
+shown at the screen at a time. As it can be seen on Figure 4, the dimensions used for viewing 
+the address book are x=<i>d.1</i> and y=<i>d.2</i>. Rotating the dimensions to 
+x=<i>d.marriage</i> and y=<i>d.children</i> shows the family tree, as in Figure 5.</p>
+
+<p>The address book and the family tree could be combined with further applitudes. For example, 
+a cell representing a person could also be connected to photographs and emails having to do 
+with that person. Simply all related information could be connected so that it is easily accessible. 
+A consequence of the ZigZag structure is that all connections are two-directional, which means 
+that navigating between related information is easy.</p>
+
+<p>3.2 Utility of GZigZag</p>
+
+<p>ZigZag offers several advantages compared with existing computer systems. To begin with, as Nelson (pers.com., 25 August 2000) usually 
+remarks after showing his <i>Holm Family Demo</i>, "we did not create a genealogy program". Modeling a complicated structure such as the family 
+tree on usual computer systems would require creating a specific program for that purpose. Modeling a complicated structure using 
+GZigZag requires only creating of new cells and connecting them along dimensions.</p> 
+
+<p>Remarkably, there are no separate files and applications in ZigZag. As seen above, the same 
+cells can simultaneously be part of different structures without any restrictive boundaries. 
+Thus, a multimedia author using GZigZag would not have the same problem as the multimedia 
+author described in 2.1. Connecting the same cells in various structures also facilitates updating 
+information. Updating the last name of a newly married aunt in the family tree and address book 
+requires updating only one cell.</p> 
+
+<p>In addition to this, ZigZag is a more flexible way to arrange information than the conventional 
+files and folders model. A certain piece of information is found by following the connections 
+that the user has previously made based on his associations. Hence, a user of GZigZag does 
+not need to remember file names in order to find the right information. The writer looking for 
+a document containing an interesting paragraph about Vilma (described in 2.1) could simply 
+follow a connection made previously. Also, moving between different versions of the same 
+paragraph is simple when using the Xanadu content model.</p>
+
+<p>Finally, ZigZag separates the structure and visualization of information. This is somewhat 
+similar to HTML 4.0 and CSS, but ZigZag generalizes this: all structures and all visualizations 
+are possible. The same GZigZag structure can be used in different media from mobile 
+phones to the immersive virtual reality of the CAVE, because  different visualizations 
+can be constructed to take full advantage of each medium.</p>
+
+<p>3. CONCLUSION AND FUTURE WORK</p>
+
+<p>The primary purpose of this article, which is the first publication of the Hyperstructure Group, 
+is to present a short summary of our ongoing work, especially GZigZag. This is not a simple 
+task because we are dealing with such a different view of the computer. Indeed, the difficulty 
+of explaining the new ideas to people has been one of the main problems of Nelson's broader 
+Xanadu project.</p> 
+
+<p>In the near future we are focused on developing a stable, working GZigZag on the Java 
+platform and cellular language Clang, which would make programming easier.  We are also 
+planning a network protocol for exchanging cells between computers
+and developing applitudes for several purposes in order to learn more about the system.</p> 
+
+<p>We believe that Nelson's ideas are creative, excellent, original and that they should finally be 
+understood and implemented. Our long-term goal is to develop a computer system we would 
+like to use ourselves. ;-)</p>
+
+<p>Everyone interested in our project is welcome to test and work on the current version of GZigZag, 
+which can be downloaded from <a href="http://gzigzag.sourceforge.net">the project's homepage</a>. GZigZag is a free software project: the 
+source code is released under the LGPL license and interested parties are welcome to join 
+our mailing list. By the time this article is published, we hope to have released the first stable 
+version (recommended for non-developers). "Patches",  as people of the free software 
+community say, and any other ideas of developing the system are gladly accepted.</p>
+
+<p>ACKNOWLEDGEMENTS</p>
+
+<p>We would like to thank Theodor Holm Nelson and Marlene Mallicoat for our collaboration. 
+We would also like to thank the other members of the Hyperstructure Group: Tuukka Hastrup, 
+Antti-Juhani Kaijanaho and Vesa Parkkinen.</p>
+
+<p>FOOTNOTES</p>
+
+<p><a name="1">1 According to Fowler (1986: 35, 42) defamiliarization is the use of a strategy to force us to look at familiar things in a critical way, to see the 
+absurdity of a familiar object. Criticism, as Fowler sees it, is not a negative practice. The basic motivation for criticism is "healthily sceptical 
+inquisitiveness", which can give a stimulus to developing things for better (Fowler 1986: 34).</a></p>
+
+<p><a name="2">2 If a person has been married several times, a mechanism called cloning is used to represent this in the structure. However, 
+this is beyond the scope of this article.</a></p>
+
+<p>REFERENCES</p>
+
+<p><u>Print References</u></p>
+
+<p>Fowler, Roger (1986). <i>Linguistic Criticism</i>. Oxford: Oxford University Press.</p>
+
+<p><u>Electronic References</u></p>
+
+<p>Bush, Vannevar (1945). <i>As We May Think</i>. <br>
+Available in the Internet: <a href="http://www.theatlantic.com/unbound/flashbks/computer/bushf.htm">
+http://www.theatlantic.com/unbound/flashbks/computer/bushf.htm</a></p> 
+
+<p>Engelbart, Douglas (1962). <i>Augmenting Human Intellect: A Conceptual Framework. </i> <br>
+Available in the Internet: <a href="http://www.histech.rwth-aachen.de/www/quellen/engelbart/ahi62index.html">
+http://www.histech.rwth-aachen.de/www/quellen/engelbart/ahi62index.html</a></p>
+
+<p>Nelson, Ted (1999a). <i>Ted Nelson's Computer Paradigm, Expressed as One-Liners.</i> <br>
+Available in the Internet: <a href="http://www.sfc.keio.ac.jp/~ted/TN/WRITINGS/TCOMPARADIGM/tedCompOneLiners.html">
+http://www.sfc.keio.ac.jp/~ted/TN/WRITINGS/TCOMPARADIGM/tedCompOneLiners.html</a></p>
+
+<p>Nelson, Ted (1999b). <i>ZX Views.</i><br>
+Available in the Internet: <a href="http://www.xanadu.com/FW99/ZXviews.html">
+http://www.xanadu.com/FW99/ZXviews.html</a></p>
+
+<p><u>Other References</u>
+
+<p>Nelson, Ted. Lectures at the University of Jyväskylä. 7 February 2000 & 30 August 2000.</p>
+
+<p>Nelson, Ted. Conversation with the authors. 25 August 2000.</p>
+
+</blockquote>
+</body>
+</html>
+
+
+
+
+

Documentation/CyberText/rank1vert.dia

@@ -0,0 +1,601 @@
+<?xml version="1.0"?>
+<diagram xmlns:dia="http://www.lysator.liu.se/~alla/dia/">
+  <diagramdata>
+    <attribute name="background">
+      <color val="#ffffff"/>
+    </attribute>
+    <attribute name="paper">
+      <composite type="paper">
+        <attribute name="name">
+          <string>#A4#</string>
+        </attribute>
+        <attribute name="tmargin">
+          <real val="2.82"/>
+        </attribute>
+        <attribute name="bmargin">
+          <real val="2.82"/>
+        </attribute>
+        <attribute name="lmargin">
+          <real val="2.82"/>
+        </attribute>
+        <attribute name="rmargin">
+          <real val="2.82"/>
+        </attribute>
+        <attribute name="is_portrait">
+          <boolean val="true"/>
+        </attribute>
+        <attribute name="scaling">
+          <real val="1"/>
+        </attribute>
+        <attribute name="fitto">
+          <boolean val="false"/>
+        </attribute>
+      </composite>
+    </attribute>
+  </diagramdata>
+  <layer name="Background" visible="true">
+    <object type="Standard - Box" version="0" id="O0">
+      <attribute name="obj_pos">
+        <point val="1,1"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="0.95,0.95;5.05,10.05"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="1,1"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="4"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="9"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O1">
+      <attribute name="obj_pos">
+        <point val="3,2"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="2.597,1.2069;3.403,2.2069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#A#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="3,2"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O2">
+      <attribute name="obj_pos">
+        <point val="3,3.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="2.597,2.7069;3.403,3.7069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#B#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="3,3.5"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Line" version="0" id="O3">
+      <attribute name="obj_pos">
+        <point val="1,2.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="0.95,2.45;5.05,2.55"/>
+      </attribute>
+      <attribute name="conn_endpoints">
+        <point val="1,2.5"/>
+        <point val="5,2.5"/>
+      </attribute>
+      <attribute name="numcp">
+        <int val="1"/>
+      </attribute>
+    </object>
+    <object type="Standard - Line" version="0" id="O4">
+      <attribute name="obj_pos">
+        <point val="5,4"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="0.95,3.95;5.05,4.05"/>
+      </attribute>
+      <attribute name="conn_endpoints">
+        <point val="5,4"/>
+        <point val="1,4"/>
+      </attribute>
+      <attribute name="numcp">
+        <int val="1"/>
+      </attribute>
+    </object>
+    <object type="Standard - Line" version="0" id="O5">
+      <attribute name="obj_pos">
+        <point val="1,5.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="0.95,5.45;5.05,5.55"/>
+      </attribute>
+      <attribute name="conn_endpoints">
+        <point val="1,5.5"/>
+        <point val="5,5.5"/>
+      </attribute>
+      <attribute name="numcp">
+        <int val="1"/>
+      </attribute>
+      <connections>
+        <connection handle="0" to="O0" connection="3"/>
+        <connection handle="1" to="O0" connection="4"/>
+      </connections>
+    </object>
+    <object type="Standard - Line" version="0" id="O6">
+      <attribute name="obj_pos">
+        <point val="1,8.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="0.95,8.45;5.05,8.55"/>
+      </attribute>
+      <attribute name="conn_endpoints">
+        <point val="1,8.5"/>
+        <point val="5,8.5"/>
+      </attribute>
+      <attribute name="numcp">
+        <int val="1"/>
+      </attribute>
+    </object>
+    <object type="Standard - Line" version="0" id="O7">
+      <attribute name="obj_pos">
+        <point val="1,7"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="0.95,6.95;5.05,7.05"/>
+      </attribute>
+      <attribute name="conn_endpoints">
+        <point val="1,7"/>
+        <point val="5,7"/>
+      </attribute>
+      <attribute name="numcp">
+        <int val="1"/>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O8">
+      <attribute name="obj_pos">
+        <point val="3,5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="2.597,4.2069;3.403,5.2069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#C#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="3,5"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O9">
+      <attribute name="obj_pos">
+        <point val="3,6.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="2.597,5.7069;3.403,6.7069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#D#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="3,6.5"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O10">
+      <attribute name="obj_pos">
+        <point val="3,8"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="2.597,7.2069;3.403,8.2069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#E#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="3,8"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O11">
+      <attribute name="obj_pos">
+        <point val="3,9.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="2.597,8.7069;3.403,9.7069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#F#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="3,9.5"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Line" version="0" id="O12">
+      <attribute name="obj_pos">
+        <point val="6,1"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="5.15,0.15;6.85,10.85"/>
+      </attribute>
+      <attribute name="conn_endpoints">
+        <point val="6,1"/>
+        <point val="6,10"/>
+      </attribute>
+      <attribute name="numcp">
+        <int val="1"/>
+      </attribute>
+      <attribute name="line_width">
+        <real val="0.1"/>
+      </attribute>
+      <attribute name="end_arrow">
+        <enum val="3"/>
+      </attribute>
+      <attribute name="end_arrow_length">
+        <real val="0.8"/>
+      </attribute>
+      <attribute name="end_arrow_width">
+        <real val="0.8"/>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O13">
+      <attribute name="obj_pos">
+        <point val="7,5.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="5.991,4.7069;8.009,5.7069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#d.2#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="7,5.5"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O14">
+      <attribute name="obj_pos">
+        <point val="9,2.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="8.95,2.45;13.05,8.55"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="9,2.5"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="4"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="6"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Line" version="0" id="O15">
+      <attribute name="obj_pos">
+        <point val="9,4"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="8.95,3.95;13.05,4.05"/>
+      </attribute>
+      <attribute name="conn_endpoints">
+        <point val="9,4"/>
+        <point val="13,4"/>
+      </attribute>
+      <attribute name="numcp">
+        <int val="1"/>
+      </attribute>
+    </object>
+    <object type="Standard - Line" version="0" id="O16">
+      <attribute name="obj_pos">
+        <point val="13,2.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="8.95,2.45;13.05,2.55"/>
+      </attribute>
+      <attribute name="conn_endpoints">
+        <point val="13,2.5"/>
+        <point val="9,2.5"/>
+      </attribute>
+      <attribute name="numcp">
+        <int val="1"/>
+      </attribute>
+      <connections>
+        <connection handle="0" to="O14" connection="2"/>
+        <connection handle="1" to="O14" connection="0"/>
+      </connections>
+    </object>
+    <object type="Standard - Line" version="0" id="O17">
+      <attribute name="obj_pos">
+        <point val="9,5.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="8.95,5.45;13.05,5.55"/>
+      </attribute>
+      <attribute name="conn_endpoints">
+        <point val="9,5.5"/>
+        <point val="13,5.5"/>
+      </attribute>
+      <attribute name="numcp">
+        <int val="1"/>
+      </attribute>
+      <connections>
+        <connection handle="0" to="O14" connection="3"/>
+        <connection handle="1" to="O14" connection="4"/>
+      </connections>
+    </object>
+    <object type="Standard - Line" version="0" id="O18">
+      <attribute name="obj_pos">
+        <point val="9,7"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="8.95,6.95;13.05,7.05"/>
+      </attribute>
+      <attribute name="conn_endpoints">
+        <point val="9,7"/>
+        <point val="13,7"/>
+      </attribute>
+      <attribute name="numcp">
+        <int val="1"/>
+      </attribute>
+    </object>
+    <object type="Standard - Line" version="0" id="O19">
+      <attribute name="obj_pos">
+        <point val="9,5.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="8.95,5.45;13.05,5.55"/>
+      </attribute>
+      <attribute name="conn_endpoints">
+        <point val="9,5.5"/>
+        <point val="13,5.5"/>
+      </attribute>
+      <attribute name="numcp">
+        <int val="1"/>
+      </attribute>
+      <connections>
+        <connection handle="0" to="O14" connection="3"/>
+        <connection handle="1" to="O14" connection="4"/>
+      </connections>
+    </object>
+    <object type="Standard - Text" version="0" id="O20">
+      <attribute name="obj_pos">
+        <point val="11,3.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="10.597,2.7069;11.403,3.7069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#G#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="11,3.5"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O21">
+      <attribute name="obj_pos">
+        <point val="11,5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="10.597,4.2069;11.403,5.2069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#H#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="11,5"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O22">
+      <attribute name="obj_pos">
+        <point val="11,6.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="10.597,5.7069;11.403,6.7069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#I#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="11,6.5"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O23">
+      <attribute name="obj_pos">
+        <point val="11,8"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="10.597,7.2069;11.403,8.2069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#J#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="11,8"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+  </layer>
+</diagram>

Documentation/CyberText/rank2vert.dia

@@ -0,0 +1,375 @@
+<?xml version="1.0"?>
+<diagram xmlns:dia="http://www.lysator.liu.se/~alla/dia/">
+  <diagramdata>
+    <attribute name="background">
+      <color val="#ffffff"/>
+    </attribute>
+    <attribute name="paper">
+      <composite type="paper">
+        <attribute name="name">
+          <string>#A4#</string>
+        </attribute>
+        <attribute name="tmargin">
+          <real val="2.82"/>
+        </attribute>
+        <attribute name="bmargin">
+          <real val="2.82"/>
+        </attribute>
+        <attribute name="lmargin">
+          <real val="2.82"/>
+        </attribute>
+        <attribute name="rmargin">
+          <real val="2.82"/>
+        </attribute>
+        <attribute name="is_portrait">
+          <boolean val="true"/>
+        </attribute>
+        <attribute name="scaling">
+          <real val="1"/>
+        </attribute>
+        <attribute name="fitto">
+          <boolean val="false"/>
+        </attribute>
+      </composite>
+    </attribute>
+  </diagramdata>
+  <layer name="Background" visible="true">
+    <object type="Standard - Box" version="0" id="O0">
+      <attribute name="obj_pos">
+        <point val="1,1"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="0.95,0.95;5.05,2.55"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="1,1"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="4"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O1">
+      <attribute name="obj_pos">
+        <point val="1,2.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="0.95,2.45;5.05,4.05"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="1,2.5"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="4"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O2">
+      <attribute name="obj_pos">
+        <point val="1,4"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="0.95,3.95;5.05,5.55"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="1,4"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="4"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O3">
+      <attribute name="obj_pos">
+        <point val="9,1"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="8.95,0.95;13.05,2.55"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="9,1"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="4"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O4">
+      <attribute name="obj_pos">
+        <point val="9,2.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="8.95,2.45;13.05,4.05"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="9,2.5"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="4"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Line" version="0" id="O5">
+      <attribute name="obj_pos">
+        <point val="6,1"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="5.15,0.15;6.85,6.35"/>
+      </attribute>
+      <attribute name="conn_endpoints">
+        <point val="6,1"/>
+        <point val="6,5.5"/>
+      </attribute>
+      <attribute name="numcp">
+        <int val="1"/>
+      </attribute>
+      <attribute name="line_width">
+        <real val="0.1"/>
+      </attribute>
+      <attribute name="end_arrow">
+        <enum val="3"/>
+      </attribute>
+      <attribute name="end_arrow_length">
+        <real val="0.8"/>
+      </attribute>
+      <attribute name="end_arrow_width">
+        <real val="0.8"/>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O6">
+      <attribute name="obj_pos">
+        <point val="7,3.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="5.991,2.7069;8.009,3.7069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#d.1#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="7,3.5"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O7">
+      <attribute name="obj_pos">
+        <point val="-8,12"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="-8,11.2069;-8,12.2069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>##</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="-8,12"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O8">
+      <attribute name="obj_pos">
+        <point val="3,2"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="2.597,1.2069;3.403,2.2069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#A#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="3,2"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O9">
+      <attribute name="obj_pos">
+        <point val="3,3.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="2.597,2.7069;3.403,3.7069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#G#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="3,3.5"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O10">
+      <attribute name="obj_pos">
+        <point val="11,2"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="10.597,1.2069;11.403,2.2069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#F#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="11,2"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O11">
+      <attribute name="obj_pos">
+        <point val="11,3.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="10.597,2.7069;11.403,3.7069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#J#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="11,3.5"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O12">
+      <attribute name="obj_pos">
+        <point val="3,5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="2.597,4.2069;3.403,5.2069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#D#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="3,5"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+  </layer>
+</diagram>

Documentation/CyberText/rank3both.dia

@@ -0,0 +1,745 @@
+<?xml version="1.0"?>
+<diagram xmlns:dia="http://www.lysator.liu.se/~alla/dia/">
+  <diagramdata>
+    <attribute name="background">
+      <color val="#ffffff"/>
+    </attribute>
+    <attribute name="paper">
+      <composite type="paper">
+        <attribute name="name">
+          <string>#A4#</string>
+        </attribute>
+        <attribute name="tmargin">
+          <real val="2.82"/>
+        </attribute>
+        <attribute name="bmargin">
+          <real val="2.82"/>
+        </attribute>
+        <attribute name="lmargin">
+          <real val="2.82"/>
+        </attribute>
+        <attribute name="rmargin">
+          <real val="2.82"/>
+        </attribute>
+        <attribute name="is_portrait">
+          <boolean val="true"/>
+        </attribute>
+        <attribute name="scaling">
+          <real val="1"/>
+        </attribute>
+        <attribute name="fitto">
+          <boolean val="false"/>
+        </attribute>
+      </composite>
+    </attribute>
+  </diagramdata>
+  <layer name="Background" visible="true">
+    <object type="Standard - Box" version="0" id="O0">
+      <attribute name="obj_pos">
+        <point val="4,5.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="3.95,5.45;8.05,7.05"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="4,5.5"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="4"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O1">
+      <attribute name="obj_pos">
+        <point val="9,5.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="8.95,5.45;13.05,7.05"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="9,5.5"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="4"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O2">
+      <attribute name="obj_pos">
+        <point val="4,7"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="3.95,6.95;8.05,8.55"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="4,7"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="4"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O3">
+      <attribute name="obj_pos">
+        <point val="14,5.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="13.95,5.45;18.05,7.05"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="14,5.5"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="4"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O4">
+      <attribute name="obj_pos">
+        <point val="4,8.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="3.95,8.45;8.05,10.05"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="4,8.5"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="4"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O5">
+      <attribute name="obj_pos">
+        <point val="14,7"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="13.95,6.95;18.05,8.55"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="14,7"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="4"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O6">
+      <attribute name="obj_pos">
+        <point val="14,8.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="13.95,8.45;18.05,10.05"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="14,8.5"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="4"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O7">
+      <attribute name="obj_pos">
+        <point val="9,7"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="8.95,6.95;13.05,8.55"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="9,7"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="4"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O8">
+      <attribute name="obj_pos">
+        <point val="9,8.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="8.95,8.45;13.05,10.05"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="9,8.5"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="4"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O9">
+      <attribute name="obj_pos">
+        <point val="19,8.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="18.95,8.45;23.05,10.05"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="19,8.5"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="4"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O10">
+      <attribute name="obj_pos">
+        <point val="6,6.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="5.597,5.7069;6.403,6.7069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#A#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="6,6.5"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O11">
+      <attribute name="obj_pos">
+        <point val="6,8"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="5.597,7.2069;6.403,8.2069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#B#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="6,8"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O12">
+      <attribute name="obj_pos">
+        <point val="6,9.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="5.597,8.7069;6.403,9.7069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#C#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="6,9.5"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O13">
+      <attribute name="obj_pos">
+        <point val="11,6.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="10.597,5.7069;11.403,6.7069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#G#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="11,6.5"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O14">
+      <attribute name="obj_pos">
+        <point val="11,8"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="10.597,7.2069;11.403,8.2069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#H#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="11,8"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O15">
+      <attribute name="obj_pos">
+        <point val="11,9.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="10.597,8.7069;11.403,9.7069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#I#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="11,9.5"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O16">
+      <attribute name="obj_pos">
+        <point val="16,6.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="15.597,5.7069;16.403,6.7069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#D#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="16,6.5"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O17">
+      <attribute name="obj_pos">
+        <point val="16,8"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="15.597,7.2069;16.403,8.2069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#E#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="16,8"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O18">
+      <attribute name="obj_pos">
+        <point val="16,9.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="15.597,8.7069;16.403,9.7069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#F#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="16,9.5"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O19">
+      <attribute name="obj_pos">
+        <point val="21,9.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="20.597,8.7069;21.403,9.7069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#J#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="21,9.5"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Line" version="0" id="O20">
+      <attribute name="obj_pos">
+        <point val="3,4"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="2.15,3.15;21.85,4.85"/>
+      </attribute>
+      <attribute name="conn_endpoints">
+        <point val="3,4"/>
+        <point val="21,4"/>
+      </attribute>
+      <attribute name="numcp">
+        <int val="1"/>
+      </attribute>
+      <attribute name="line_width">
+        <real val="0.1"/>
+      </attribute>
+      <attribute name="end_arrow">
+        <enum val="3"/>
+      </attribute>
+      <attribute name="end_arrow_length">
+        <real val="0.8"/>
+      </attribute>
+      <attribute name="end_arrow_width">
+        <real val="0.8"/>
+      </attribute>
+    </object>
+    <object type="Standard - Line" version="0" id="O21">
+      <attribute name="obj_pos">
+        <point val="3,4"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="2.15,3.15;3.85,11.35"/>
+      </attribute>
+      <attribute name="conn_endpoints">
+        <point val="3,4"/>
+        <point val="3,10.5"/>
+      </attribute>
+      <attribute name="numcp">
+        <int val="1"/>
+      </attribute>
+      <attribute name="line_width">
+        <real val="0.1"/>
+      </attribute>
+      <attribute name="end_arrow">
+        <enum val="3"/>
+      </attribute>
+      <attribute name="end_arrow_length">
+        <real val="0.8"/>
+      </attribute>
+      <attribute name="end_arrow_width">
+        <real val="0.8"/>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O22">
+      <attribute name="obj_pos">
+        <point val="11,4"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="9.991,3.2069;12.009,4.2069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#d.1#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="11,4"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O23">
+      <attribute name="obj_pos">
+        <point val="2,8"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="0.991,7.2069;3.009,8.2069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#d.2#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="2,8"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - BezierLine" version="0" id="O24">
+      <attribute name="obj_pos">
+        <point val="6,10"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="5.95,0.45;16.05,16.55"/>
+      </attribute>
+      <attribute name="bez_points">
+        <point val="6,10"/>
+        <point val="6,16.5"/>
+        <point val="16,0.5"/>
+        <point val="16,5.5"/>
+      </attribute>
+      <connections>
+        <connection handle="0" to="O4" connection="6"/>
+        <connection handle="3" to="O3" connection="1"/>
+      </connections>
+    </object>
+    <object type="Standard - BezierLine" version="0" id="O25">
+      <attribute name="obj_pos">
+        <point val="11,10"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="10.95,1.45;21.05,16.05"/>
+      </attribute>
+      <attribute name="bez_points">
+        <point val="11,10"/>
+        <point val="11,16"/>
+        <point val="21,1.5"/>
+        <point val="21,8.5"/>
+      </attribute>
+      <connections>
+        <connection handle="0" to="O8" connection="6"/>
+        <connection handle="3" to="O9" connection="1"/>
+      </connections>
+    </object>
+    <object type="Standard - Line" version="0" id="O26">
+      <attribute name="obj_pos">
+        <point val="8,6.25"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="7.95,6.2;9.05,6.3"/>
+      </attribute>
+      <attribute name="conn_endpoints">
+        <point val="8,6.25"/>
+        <point val="9,6.25"/>
+      </attribute>
+      <attribute name="numcp">
+        <int val="1"/>
+      </attribute>
+      <connections>
+        <connection handle="0" to="O0" connection="4"/>
+        <connection handle="1" to="O1" connection="3"/>
+      </connections>
+    </object>
+    <object type="Standard - Line" version="0" id="O27">
+      <attribute name="obj_pos">
+        <point val="14,6.25"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="12.95,6.2;14.05,6.3"/>
+      </attribute>
+      <attribute name="conn_endpoints">
+        <point val="14,6.25"/>
+        <point val="13,6.25"/>
+      </attribute>
+      <attribute name="numcp">
+        <int val="1"/>
+      </attribute>
+      <connections>
+        <connection handle="0" to="O3" connection="3"/>
+        <connection handle="1" to="O1" connection="4"/>
+      </connections>
+    </object>
+    <object type="Standard - Line" version="0" id="O28">
+      <attribute name="obj_pos">
+        <point val="18,9.25"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="17.95,9.2;19.05,9.3"/>
+      </attribute>
+      <attribute name="conn_endpoints">
+        <point val="18,9.25"/>
+        <point val="19,9.25"/>
+      </attribute>
+      <attribute name="numcp">
+        <int val="1"/>
+      </attribute>
+      <connections>
+        <connection handle="0" to="O6" connection="4"/>
+        <connection handle="1" to="O9" connection="3"/>
+      </connections>
+    </object>
+  </layer>
+</diagram>

Documentation/DesignProblems/Makefile

@@ -0,0 +1,11 @@
+DIAGRAMS=linkorder.png beamorder.png
+
+all : dp.html dp-ns4.html
+
+dp.html: dp.wml $(DIAGRAMS)
+
+dp-ns4.html: dp.wml $(DIAGRAMS)
+
+include ../lib.mk
+
+

Documentation/DesignProblems/dp.wml

@@ -0,0 +1,680 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+   "http://www.w3.org/TR/html4/strict.dtd"> 
+<!--
+	NOTE! This file uses WML 2.0.1
+
+	PLEASE PLEASE PLEASE don't edit .HTML. Edit .WML!!!! Actually,
+	it's more important for you since your changes will be LOST FOREVER
+	if you edit the .HTML files.
+ -->
+
+<html>
+ <head>
+  <title>The major internal design problems left in GZigZag</title>
+#include '../wmlinc/article.wml'
+ </head>
+ <body>
+{: [[s/(?<!>)(d\.+\w+)/<code>\1<\/code>/g]]
+<H1>The major internal design problems left in GZigZag</H1>
+<pre>$Id: dp.wml,v 1.14 2000/08/15 05:19:18 tjl Exp $</pre>
+<grid layout=3x3 spacing=20>
+ <cell> <b>Tuomas Lukka</b> <br>
+ 	<code>lukka@iki.fi</code><br>
+        Dept. of Mathematical Information Technology <br>
+	University of Jyväskylä 
+ </cell>
+</grid>
+
+<toc>
+
+<!-- Use like <figure img="foo.png" width=...>caption</figure> -->
+
+<p>
+This is a short exposition of the design problems currently in ZigZag
+(as of June 2000). The intent is to eventually evolve this into an exposition
+of the internal design of GZigZag, after the problems are solved. But
+at the moment most of the problems still exist.
+
+<warn>
+
+<h2>Introduction</h2>
+
+	<p> 
+	This document is intended as an internal discussion document
+	on the most difficult design problems for the GZigZag source code.
+	This is work-in-progress: if there are any unclear parts, feel
+	free to ask me to clarify things.
+
+<h2>Device-independent Floating Graphics</h2>
+
+	<h3>FloatingWorld Graphics</h3>
+
+	<p>
+	The FloatingWorld graphics model built on top of ZigZag is based
+	on flexibly plotting objects defined by cells on the screen.
+	ZigZag rasters are simply a special case of this: the coordinates
+	are given by hopping along ZigZag ranks and the objects rendered
+	are simply the cells and the texts inside them.
+
+	<p>
+	Conceptually, there are two kinds of objects shown on the
+	screen: <i>flobs</i> and <i>relations</i>. Also, there are three
+	different processes in the background: <i>where</i> are flobs
+	rendered, <i>what kind</i> of flobs are rendered and <i>what
+	relationships</i> between them should be shown. All these are
+	relatively independent of each other and should be clearly
+	decoupled in the backend.
+
+	<p>
+	Animation has been supported from very early on in GZigZag with
+	excellent results: the human eye can use the motion to understand
+	the relation of the different views in time much better than
+	if the views are just switched without the intermediate frames.
+	This feature should be global: if the same object is shown in two
+	consequent views, it should animate from the previous view to the
+	next to show the deep relationship between the two appearances.
+	Even a simple linear interpolation, without any regard to the
+	true structure of the transformation between the two views is
+	astonishingly helpful.	It is easy to see that animation mostly
+	concerns the flobs which must interpolate their coordinates frame
+	by frame between rasters. In fact, currently the links are not
+	shown when animating; this does not appear to be a significant
+	problem to the human observer: maintaining a high frame rate is
+	much more important than giving a complete picture.
+
+	<p>
+	In addition to animation, depth perception of the human eye
+	is misused in the vanishing raster to a great advantage: cells
+	further away from the cursor are shown smaller and grayer and
+	are rendered behind the cells closer to the cursor. I term this a
+	misuse since there is no 3D model behind: it's just an algorithm
+	that lays out cells that happen to look smaller and grayer and
+	thus further away.
+
+	<h3>The desired level of generality</h3>
+
+	We shall take four views as an example of the generality the system
+	has to offer.
+	<ul>
+	 <li>
+		Normal, box-and-stick view (loose-brick)
+	 <li>
+		Tight-brick view: the cells are drawn right next to each
+		other.	The line drawn between the cells (or on edges)
+		tells what kind of edge it is (connected, no connection,
+		connection underneath the other cell).
+	 <li>
+		Loose-brick view but with variable-sized content of cells:
+		vstreams or images.
+	 <li>
+		Email flobs: emails on a coordinate system, connected
+		with lines indicating reply-to relationships. The flobs
+		may show the content, diminished as the view moves away
+		from the cursor.
+	</ul>
+
+	<h3>Problems</h3>
+
+
+	<figure img="linkorder.png" width="250px">
+		A simple case where rendering a link in one go gives
+		suboptimal results.
+	</figure>
+
+	<figure img="beamorder.png" width="250px">
+		A beam with cells is even more complicated: the beam
+		has to be between the text and the cell background but
+		behind any other cells on the way to avoid cluttering
+		the screen.  If the beams' borders should float above
+		the beams, then this gets even more difficult.
+	</figure>
+
+	<p>
+	A fairly short-term goal in the expansion of GZigZag is to make
+	it support 3D graphics using OpenGL, as well as retain the current
+	functionality using pure Java graphics. Especially useful would be
+	the ability to use the 2D views directly through the OpenGL layer,
+	as well as 3D views, and the ability to animate between the two.
+
+	<p>
+	<dl>
+	 <dt>Reusability of views
+	 <dt>Flexibility
+	  <dd>As an example, using an existing raster but putting an image
+	      or a vstream (somehow connected to the cell) instead of 
+	      the text into the cell should be simple. 
+	 <dt>Simplicity
+	  <dd>The system 
+	 <dt>Performance
+	</dl>
+
+	<p>
+	If small factories are used for letting the rasters create cells,
+	handling depth gets more complicated. 
+
+	<p>
+	There are also interesting problems in the rendering order of
+	links: if there is a link between cells that are at different
+	depths, then which cells should be in front. It is especially
+	difficult to include something like beams into this framework,
+	if a Z-buffer and a real third coordinate is not used.
+	One possibility is to split all links and beams in the middle
+	and render the two halves independently.  However, as seen in
+	the beam figure, that will not be enough.
+
+
+	<h3>Potential solutions</h3>
+
+	<p>
+	Let us start from the obvious.
+
+	<p>
+	For each raster, the locations and appearances (and the depths
+	for rendering) of the flobs must be stored somewhere quickly
+	accessible for the animation between rasters.
+
+	<p>
+	The raster must ask the flob-producer what size and aspect ratio
+	would be most suitable (given a shrinking factor). Being able to
+	cache something that was calculated (such as a line breaking)
+	would be most beneficial.  Of course, depending on the form of
+	the raster, it may or may not accept the size and aspect ratio
+	given by the flob producer.  The flobs are internally cached as
+	objects that know how to render themselves and how to interpolate
+	between two keyframes.
+
+	<p>
+	The links are produced <em>after</em> rastering, from the
+	coordinates of the flobs. This operation is thus well encapsulated
+	from changing rasters.	In fact, the links do not even need to
+	be made into self-standing objects at all times: all that is
+	needed is that the FlobSet knows to call a certain method of a
+	certain object to plot links.
+
+	<p>
+	These considerations produce a rather different picture
+	from the current one. The classes <code>Flob</code> and
+	<code>FlobSet</code> would be the natural starting point. A
+	FlobSet, unlike the current ZZCanvas, would only store the flobs
+	and not the connections. The connections could be drawn just as
+	the flobset is being rendered from back to front.
+
+	<p>
+	One interesting point regarding the identification of Flobs from
+	the FlobSet is that the FlobSet may be hierarchical in nature.
+	For example when doing the VStreams-in-Cells raster, the same
+	vstream might be shown in two different cells (clones of each
+	other).  Now, if flobs were identified just by their cell, then
+	the flobs for the spans of text would be identical and therefore
+	interpolated animation could do very strange things.  The trivial
+	solution to this is to allow container flobs to exist, which
+	exist just to identify that certain cells are accessed through
+	a certain other cell. If the FlobSet has knowledge about this,
+	it is easy to both treat the FlobSet as flat (for e.g. beams),
+	or as the hierarchy (for identification of the corresponding
+	flob in another FlobSet for animation).
+
+	<p>
+	This solution is currently being tested as of 20000806.
+
+	<h4>Problems with the hierarchy</h4>
+
+	<p>
+	The hierarchy does not solve all the problems and
+	brings some new ones.
+	Some operations use hierarchy, some don't.
+	<dl>
+	 <dt>Depth-ordering
+	  <dd>May be done with hierarchy (so the whole hierarchy branch
+	      has a depth - effect like overlapping windows or
+	      without hierarchy - effect like a three-dimensional cloud.
+	      Both effects are probably useful in different situations.
+	 <dt>Animation
+	  <dd>Hierarchy is taken into account: it informs which instances
+	      of a cell animate to which other instances.
+	 <dt>Link / beam display
+	  <dd>Hierarchy is not relevant to these except that sometimes
+	      links/beams inside the same branch may be hidden.
+	</dl>
+
+	<p>
+	Because the hierarchy is kind of optional,
+	the hierarchy in the current prototype
+	is simply handled by identifying
+	each flob with a string ("path") and a cell.
+	This seems to give both enough detail and efficiency.
+
+	<h4>Decorations</h4>
+	
+	<p>
+	Another interesting feature with the views are decorations:
+	things that either connect flobs between each other or
+	show some relationship in some other way
+	(for example, the three-line thing that shows the directions
+	of the coordinate axes).
+
+	<p>
+	These decorations aren't considered first-class citizens like
+	flobs in the current model. 
+	This may make it possible to find extremely efficient
+	ways to implement them.
+	One obstacle to efficiency, however, is that the decorations
+	should be rendered at the same depth as the cells. If we have
+	a Z-buffer like in OpenGL, this is of course not a problem.
+
+	<p>
+	Now, there are several kinds of decorations:
+	<dl>
+	 <dt>One-off
+	  <dd>Decorations that occur once or twice in a display, such
+	      as the abovementioned coordinate thingy.
+	 <dt>Global
+	  <dd>Decorations that occur between most cells (at least,
+	      most cells at a given path), such as links in the X direction.
+	 <dt>Overriding
+	  <dd>Decorations that override global decorations for selected
+	      cells, for example if we want to show a connection that
+	      is at the same time a clone relation by a different 
+	      visual.
+	</dl>
+
+	<p>
+	In order to trample over less memory, it would be nice to
+	be able to render global decorations for a set of cells (at
+	a given depth) at once.
+
+	<p>
+	There is one situation where decorations present a problem,
+	and that is when the decorations should move with the interpolation.
+	This is generally desirable in complicated views (e.g. email-flob)
+	to provide the user with additional visual cues about the structure.
+	There is a slightly incorrect solution that get us close to where
+	we want: a decoration that wants to interpolate is named a flob
+	and it stores references to the flobs and uses their 
+	<code>interpTo</code> fields to calculate the interpolated
+	coordinates. The only problem is the depth: this algorithm does
+	not correctly alter the depth in interpolation.
+	However, when using <code>java.awt.Graphics</code> none of the other
+	flobs take care of their depths properly when interpolating so
+	it is not a problem. And if using three-D graphics, the renderer
+	can use the flobs' Z coordinates.
+
+
+<h2>Floating graphics in general.</h2>
+
+ <h3>Handles and cursors</h3>
+
+	<h4>Problem</h4>
+
+	<p>
+	One of the versions of Ted's specs specifies the following
+	structure for flob.
+	First of all, there is the central <dfn>handle cell</dfn> which
+	is the center of the flob. The flob is referred through it and
+	all the parts of the flob can be found through it.
+	That version of the spec specifies d.handle as the dimension to
+	reach the rest of the flob from the handle cell, and
+	d.ref as the dimension to use to refer to that handle cell and 
+	thereby to the whole flob. (the spec has apparently changed
+	now but the changes do not affect this problem).
+
+	<p>
+	The cells on d.ref are basically stand-ins for the whole flob,
+	kind of like clones are stand-ins for a cell. 
+	An email can be included in several mailboxes (lists of emails
+	running on d.2) by including cells that are on d.ref from
+	the original email's handle cell.
+
+	<p>
+	The problem, then, is basically about what is getting shown:
+	we'd like to be able to show
+	<ol>
+	<li> The actual flob
+	<li> The fact that a cursor is on the referring cell
+	<li> Possibly, the contents of the referring cell
+	</ol>
+	This is a problem since in the current codebase, a flob
+	is known by <em>one</em> cell, whereas the above obviously 
+	requires two cells: the referring cell and the handle cell.
+	Even more important is that the <code>FlobSet</code> knows
+	about the handle cell since otherwise connecting the flobs
+	becomes a less efficient procedure, requiring the FlobSet to
+	look at all referring cells to see whether they are included.
+
+	<p>
+	So the question really becomes: is there any point in storing
+	the referring cell in the flob structure, except as presentational
+	info about the string and cursor colors to show.
+
+	<p>
+	If ZZ is expanded to allow the user to place the text 
+	insertion cursor in a cell by a mouse click, then the referring
+	cell is obviously needed if any of its text is rendered.
+
+	<h4>Current solution</h4>
+
+	<p>
+	Well, currently this is solved by having the handle cell always
+	be the <code>Flob.c</code> and if the flob has to give out
+	other events, it can be given a different cell.
+
+
+
+	
+
+<h2>Caching before saving - new file format</h2>
+
+	<p>
+	The slowest part of the current implementation, as witnessed
+	by time testing, is writing to the file. Also, the current file
+	format does not properly allow undo & branching backtracking.
+
+	<p>
+	The goals for the system are
+	<dl>
+	 <dt>Write-caching
+	  <dd>Each cell change should not cause several system calls
+	     to occur. Rather, cell changes should be held in memory
+	     and flushed to disk in larger chunks every once in a while
+	     (as the user chooses).
+	 <dt>Undo
+	  <dd>The list of operations in memory should be usable for
+	      low-level undo operations, such as undoing writing letter
+	      by letter.
+	 <dt>Granularity
+	  <dd>The user should be able to specify that when saved to
+	      disk, only larger sets of changes are undoable. This may
+	      save a lot of space, e.g. if a number of cursor moves
+	      are compressed
+	      to one undo set, many cells will not have changed at all.
+	      This is especially important now that the character-by-character
+	      editing of cell content is also done in the structure:
+	      each insertion of a character currently saves <em>two</em>
+	      cell contents: the cell being edited and the cursor cell
+	      (giving the offset).
+	 <dt>Notifications
+	  <dd>It would be useful if the change list could also be used for
+	      change notifications: after a set of operations is completed
+	      (or at prespecified times) the list is examined for changes
+	      to cells under observation.
+	</dl>
+
+	<h3>List format</h3>
+
+	<p>
+	It is vital that the in-memory change list is compact in format
+	and extremely light-weight for Java usage as it is going to be a
+	hot spot.
+
+	<p>
+	One relatively sparing implementation would be to have one long
+	array of Object inside which every third element would be an operation,
+	and the other two would be its parameters. This way, no separate
+	Operation object would need to be created and the references to
+	operations sequentially would stay memory-local: the cost 
+	of the typecast
+	of <code>Object</code> to the Operation type is negligible compared
+	to the cost of accessing two or three long arrays instead of one.
+
+	<p>
+	There would likely be one to few Operation objects per dimension object,
+	which is perfectly acceptable.
+
+	<p>
+	The long array would have the sequence stamps and would be operable
+	either for undo or for committing to disk.
+
+	<h3>Problems</h3>
+
+	<p>
+	There is one important problem with this approach: the operations
+	are fairly low-level ops: this cell connected to this one, or
+	disconnected, or whatever. 
+	The semantic information about an operation such as insertion
+	is not saved. This could be a problem with synching later on.
+
+	<h3>Notifications</h3>
+
+	<p>
+	In the following, N is the number of cells changed, B is the number
+	of observers. Also, K is the number of cells one observer typically
+	observes.
+
+	
+	<p>
+	It is important for the notification mechanism to be fast: specifying
+	a set of cells that a particular entity is interested in and scrapping
+	the whole set (when the entity is refreshed) will very likely be one
+	of the most common operations. Not trampling through a lot of memory
+	and being easily garbage collectible are vital considerations, as well
+	as good scaling w.r.t.~several things.
+
+	<p>
+	Observer insertion is naturally O(K) and observer removal is
+	either O(1) or O(K). 
+
+	<p>
+	If a separate hashtable is used for each observer, testing which 
+	observers to wake up is O(N*B) operation, which is not very nice.
+
+
+
+<h2>Slices</h2>
+
+<p>
+Slices are used for viewing a number of ZigZag spaces as one compound
+space, and for sending a group of cells over to another user.
+Slices are probably the most crucial aspect of the system for common use
+as they will enable collaboration and upgrading.
+
+<p>
+Among the issues here are
+<dl>
+ <dt>Permanent IDs for versions of cells
+ <dt>Specifying a group of cells for slicing.
+  <dd>This is simple when the all the cells are ones edited by the user.
+      This gets very hairy when the user wants e.g. to send a view. Which 
+      control cells are included?
+ <dt>Reconciling differences: collaborative editing.
+  <dd>A mechanism for keeping two peoples' versions of a "document"
+      in synch by sending minimal groups of cells across. 
+ <dt><code>d.cursor</code> and slices.
+  <dd>Having the cursors in the structure is both a blessing and a curse.
+      Cursors are used both for "variables" internal to the structure
+      with Clang and views' centers. 
+      Their interaction with slices and versioning is unclear to say the least.
+ <dt>Inclusion of a slice into multiple spaces
+  <dd>What a can of worms.
+ <dt>Viewing a space remotely
+  <dd>Only the cells seen should be sent over. How does <code>d.cursor</code>
+      work here?
+ <dt>The identity of dimensions
+  <dd>If a dimension is just a string, we have a namespace problem.
+      Dimension being identified with a particular cell might be a solution
+      but this is again not without its own problems.
+ <dt>Clones
+  <dd>Ted wants these to be used as a solution to many problems here.
+      But is it possible? Can all code be made to support the situation
+      where suddenly one of the cells is split into two clones when
+      the script expected them to be together.
+ <dt>Transcluding
+  <dd>Taking a cell from another space with a permanent ID and connecting
+      its transclusion somewhere in the local space - this creates a new
+      version of the cell!
+ <dt><code>d.ref</code> and <code>d.handle</code>
+  <dd>Interaction of higher-level items with the slice code?
+</dl>
+
+<p>
+And of course the really important question of what we're really after.
+Slices have distinct, but related functionalities:
+<dl>
+ <dt>Part of personal space.
+  <dd>This is what Ted's example of bringing in months of the calendar
+      from slices is about. Each day connects to a weekday on one dimension,
+      and the months connect naturally in the right order by preflets.
+      Here, the idea is that the slice connects to the "main space".
+ <dt>A fixed, distributed "package".
+  <dd>For example, the default space with the default bindings for keys, or
+      packages that demonstrate various features.
+      These are less often modified by the user and are brought in by the user
+      and attached somewhere.
+      Here, the main space connects to the slice.
+ <dt>Versioning.
+  <dd>This is rather similar to the abovementioned fixed, distributed 
+      packages: the user can attach the old version of some slice
+      somewhere, without modifying it (causing a branch) just by looking
+      and browsing it.
+      Naturally, if two versions of the same slice are brought in, the cells
+      should be connected along <code>d.version</code> or somesuch.
+  <dd>
+</ul>
+
+	<h3>Packages</h3>
+	<p>
+	Of the above functions, the most critical one for GZigZag
+	currently is the packages: distributing the main default space
+	as a slice would be a great step: then it would be possible for
+	users to start stable personal spaces which would not be needed
+	to be brought forwards for every new version of the bindings.
+
+	<p>
+	The most important problems here are cursors. Just about
+	everything else can be resolved by explicit hook cells ("hook your
+	own bindings negwards on <code>d.3</code> here").  Cursors are
+	a different matter.  They are used for several things, to name
+	a few:
+
+	<dl>
+	 <dt>Center of view
+	 <dt>Selecting dimensions from dimension lists
+	 <dt>Selecting rasters from raster lists
+	 <dt>Arbitrary selections for viewing operations
+	</dl>
+
+	<p>
+	Additionally, there is the cursor cargo dimension which allows
+	cursors to piggyback on one another - for example, combining
+	the cursors for one view and another view's X axis allows one
+	to change the dimension list for the X axis by moving the other
+	view's center.
+
+	<p>
+	The default space and other packages which have views will most
+	likely have cursors. In order for the spaces to be useful,
+	these cursors should be movable when the package-slice is
+	included and should be movable by changing the main space,
+	not the package-slice. Also, cursor cargo should be changeable.
+
+	<p>
+	There is a simple solution to these problems: the package slices'
+	own <code>d.cursor</code> and <code>d.cursor-cargo</code> are
+	mapped to some other dimensions, e.g. <code>d.ps-cursor</code>.
+	When a slice is first incorporated into the system, the
+	default cursors from the slice are copied to the global
+	<code>d.cursor</code>.	There then need to be operations on the
+	slice cell to reload or commit the cursors of a slice, which
+	simply copy the assignments of the cursors to the package-slice
+	(provided all cursors lie on cells of that package-slice as
+	they should) or copy the cursors from the package-slice to the
+	main space.
+
+	<h3>Most trivial slices</h3>
+
+	<p>
+	Because waiting for the full design to be finalized would
+	have seriously slowed down development (as the main developers
+	wouldn't be able to <em>use</em> GZZ for real work) there is
+	now a primitive slice implementation in place.	Even in its
+	rudimentary form it is surprisingly complete.  In addition,
+	this experiment gives valuable experience in the complexities
+	of implementing any types of slice systems.
+
+	<p>
+	The system works by handling two dimensions, <code>d.slices</code>
+	and (naturally) <code>d.cursor</code> specially.  These are in
+	fact the only dimensions that are allowed to connect between the
+	slices; all others are constrained to be only among the cells
+	of the same slice.
+
+	<p>
+	The dimension <code>d.slices</code> simply connects the homecells
+	of the slices in the slice order. There are no other connections
+	along this dimension and it cannot be modified.
+
+	<p>
+	<code>d.cursor</code> is a different matter. In order to be
+	useful, even the most trivial slices must allow connections that
+	transcend the slices on <code>d.cursor</code>.	In this model,
+	<code>d.cursor</code> is constrained so that the only operation
+	allowed is insertion negwards (currently the cursor is obtained
+	by going to the end of <code>d.cursor</code> poswards, which
+	will change).  Also, cells in slice 0 may be inserted to any
+	other cell but not vice versa: cells (cursors) in other slices
+	may only point to cells in the same slice.
+
+	<p>
+	These semantics are fairly simple but still their correct
+	implementation is not at all trivial, especially for
+	<code>d.cursor</code>.	The implementation uses preflets in
+	slice 0 to connect to the other slices and when reading, the
+	whole rank in slice 0 is placed before all the other cells in
+	the non-zero slice accursing the same cell, so the cursors are
+	not necessarily in the same order they were inserted in.
+
+	<h3>Adapter slices</h3>
+
+	<p>
+	One possible solution in the long term to the package-slice
+	problem is simply having adapter-like slices for the external
+	packages.  These slices would have preflets pointing to s.0 as
+	well as the external package - possibly even without intervening
+	cells.
+
+<h2>Versioning</h2>
+
+<p>
+Versioning is one of the most difficult problems in defining a ZZ space.
+This is because having a versioned space is not useful, unless
+cursors can point to past versions of cells using the normal mechanism,
+d.cursor. If views and pointing were handled outside the normal space,
+this would be no problem.
+
+<p>
+This immediately suggests the trivial but unsatisfactory solution of 
+simply not versioning d.cursor. This is unsatisfactory because d.cursor
+is used for an increasing number of things, e.g. Clang variables: what
+good would it be to have access to a previous state without being able
+to access the values of the variables.
+
+<p>
+The other solution, simply allowing retroactive changes to d.cursor
+of past cells to point to the future is more attractive but not without
+its own downsides. Let's say the user, at time 100 looks at a cell A at time 5 
+and does some changes in the space, e.g. moves the other cursor or
+writes text somewhere else, until time 105 after which he moves
+the cursor away. In this case, the rank on d.cursor from cell A would
+contain the user's viewcell at times 100, 101, 102, 103, 104 and 105.
+This is not that great either, because the algorithm that displays the
+cursor moves through d.cursor to find the coloring of the cell to show
+the colors of the cursors on it. The number of cursors on past cells would
+be compounded.
+
+<p>
+A potentially interesting solution, avoiding the preceding problem,
+is to rename d.cursor to d..cursor-past for the past cells: 
+a connection on d.cursor would mean that a current cursor is on the cell.
+This solution is attractive, as it preserves the values of all Clang
+variables "pickled" using another dimension on which they can be browsed,
+but also does not grow the number of cursors on a cell too much.
+
+
+
+
+
+:}
+</body>
+</html>
+<!--
+	vim: set syntax=html :
+-->

Documentation/DimBased/Makefile

@@ -0,0 +1,3 @@
+all : dim.dvi dim.ps
+
+include ../lib.mk

Documentation/DimBased/dim.ptex

@@ -0,0 +1,53 @@
+% BE SURE TO EDIT design.ptex
+\documentclass{article}
+
+\usepackage{rcs}
+\RCS $Date: 2000/03/04 15:45:59 $
+\RCS $Revision: 1.1 $
+\date{Rev.\RCSRevision~~\RCSDate}
+
+\title{Dimension-based thinking for ZigZag}
+\author{Tuomas J. Lukka}
+\begin{document}
+\maketitle
+
+\def\zz{ZigZag}
+
+\section{Introduction}
+
+When designing the code to implement a \zz\ space, the 
+place most people would start at would be the cell object, which would
+have a set of pointers to other cells, named with dimension names.
+However, this is not the only way to structure the internals - indeed,
+it is not necessarily a good way at all.
+
+\section{Dimension-based view}
+
+With cells, you have to always take steps to enforce the two-directional
+connection consistency rule.
+The dimension-based view starts from the realization that if we consider
+each {\em dimension} an entity by itself, this gets much simpler: 
+simply put, each dimension is a one-to-one mapping from some cells of the
+space to some other cells. 
+
+\section{Advantages}
+
+The dimension-based view has several advantages:
+\begin{itemize}
+\item {\bf Specialization}
+	It is much easier to define a single dimension object to 
+	do something different than the others, e.g. a dimension where
+	getting the {\it n}th cell is fast but inserting and deleting cells
+	is allowed to be slow.
+\item {\bf Simplicity}
+	Since one object is in charge of the both ends of a connection,
+	it is easier to avoid mistakes. Coding transient cell connections
+	is easy as well, as that object can keep tabs on the transient
+	connections separate from the stable ones.
+
+
+
+% .PS
+% box "Clang" ht 0.25
+% .PE
+% $$\box\graph$$

Documentation/FAQ

@@ -0,0 +1,262 @@
+Frequently Asked Questions about GZigZag, with answers.
+$Id: FAQ,v 1.7 2001/02/09 05:59:36 ajk Exp $
+
+All trademarks are the trademarks of their respective owners.
+
+Note that the 'I' in this document is Tuomas Lukka.
+
+=============================================================
+Section I: General questions
+
+
+1. Where to get the latest version of this FAQ?
+
+The source code for all versions of this FAQ is kept as a part of the
+GZigZag CVS repository. See the GZigZag sourceforge page at 
+	
+	http://gzigzag.sourceforge.net
+
+for accessing the source. The FAQ is in the directory Documentation/
+
+-----
+2. What is ZigZag?
+
+ZigZag, an invention of Ted Nelson, is a new type of data structure.
+
+For mathematicians, the key words would be
+
+ 	- discrete
+	- multidimensional
+	- locally euclidean
+	- with global directions (coordinate axes)
+
+and for non-mathematicians, these are explained below:
+
+	Discrete:
+		the information is stored in cells, kind of like a 
+		spreadsheet.
+
+	Multidimensional:
+		instead of two dimensions, X and Y, that a spreadsheet 
+		has, a ZigZag space can have any number of dimensions
+		which are distinguished by strings.
+
+	Locally Euclidean:
+		a spreadsheet is globally euclidean, i.e. it is a lattice.
+		ZigZag is only locally euclidean, so the neighborhood of
+		(i.e. the cells next to) a given cell looks euclidean:
+		if you go up and come down, you are back where you were before.
+
+		But if you start from location 1, and go up, left, down and
+		right, you might not get back to where you were, let's
+		say you are at location 2. But if you then go left, up, down
+		and right from location 2, you get back to location 1.
+
+		The connections in ZigZag are user-alterable so you can
+		connect any two cells along any given dimension, but
+		because of the local euclidean constraint, each cell
+		can be connected to only one cell in the positive and one
+		cell in the negative direction on each dimension.
+
+Computer scientists might note that ZigZag is an interesting special
+case of graphs.
+
+-----
+3. What is GZigZag?
+
+GZigZag is an implementation of ZigZag developed by a research group led
+by Tuomas Lukka at the university of Jyvaskyla.
+
+It is licensed under the LGPL (and XPL, the Xanadu Public License which
+is still under works).
+
+-----
+4. Who is the maintainer of GZigZag?
+
+Tuomas Lukka, <lukka@iki.fi>. He has written most of the code in GZigZag (and
+most of it while traveling on trains).
+
+This maintainership is by proxy from Ted Nelson, who has the official
+maintainership but who does not program.
+
+-----
+5. How complete/stable is GZigZag?
+
+It's pre-alpha. It is already usable for many things but it is nowhere
+near feature complete yet. 
+
+As for stability, crashes are quite rare but the development speed is high.
+
+-----
+6. What are some planned features?
+
+See Java/TODO in the distribution.
+
+-----
+7. Are there any mailing lists associated with ZigZag/GZigZag?
+
+See http://www.xanadu.com/zigzag
+
+-----
+8. How can I help?
+
+Email Tuomas Lukka <lukka@iki.fi> and ask.
+
+
+=============================================================
+Section II: Using (G)ZigZag
+
+1. How can I learn to create my own structures so that they work well?
+
+There are some ideas in the document "A Gentle Introduction to ZigZag",
+available under the 
+
+	Documentation/Gentle_Introduction
+
+directory on the CVS, or as a postscript file from the web page.
+
+=============================================================
+Section III: Questions specific to the Java version
+
+1. Why Java?
+
+Portability, garbage collection, SPEED (with JIT: for linux, IBM's
+JDK-1.1.8 is GREAT), portable graphics, easy C interface, available APIs
+(e.g. JMF), etc.
+
+You will note that I did not mention the language itself above:
+I don't like the language itself that much: I'd prefer to work in
+Perl. Unfortunately it does not provide all of these other features and
+the ones it does it does not provide as easily and conveniently as Java.
+
+-----
+1.1 Where do I get Java sources for GZigZag?
+
+If you know CVS, you can checkout module GZigZag in
+:pserver:anonymous@cvs.gzigzag.sourceforge.net:/cvsroot/gzigzag .
+Otherwise, you can use our nightly-generated source snapshots
+available at ftp://gzigzag.sourceforge.net/pub/gzigzag/snapshots/ .
+They are packaged in GNU-Zipped tar archives and in ZIP archives,
+choose whichever is best for you.
+
+The Java sources are located in the Java/ subdirectory of the full
+source tree.
+
+-----
+1.2 Where do I get precompiled class files for GZigZag?
+
+We have a build daemon that builds the current CVS version nighly and
+puts two JAR archives of it in
+ftp://gzigzag.sourceforge.net/pub/gzigzag/snapshots/ .  The
+-without-modules version contains the core GZigZag.  The -with-modules
+version is much larger and contains some additional functionality.
+
+-----
+1.5. It's WAY too slow! Are you out of your mind?
+
+No. For me, it's quite comfortable on my 233MHz Pentium 80Mb laptop.
+There are several possible reasons for this: 
+
+* You are using a Java interpreter without a JIT (Just-In-Time)
+  compiler. As mentioned in the answer to the previous question, for
+  Linux, I recommend IBM's JDK 1.1.8. Do NOT ask me about proprietary
+  operating systems - GZigZag works there but over there you're on
+  your own for platform-specific questions.  Another quite fast JVM is
+  Kaffe, but unfortunately at least some versions of Kaffe have a
+  nasty bug that makes using GigZag on it quite unpleasant.
+
+* Your Java interpreter is not using enough memory. By default, some Java
+  interpreters only use 16Megs at maximum. Try starting with
+
+	java -mx30m -ms30m foo.Main
+
+  to set it to allocate 30Megs at startup (or more if you have enough memory).
+  That way it won't be garbage collecting constantly and you may get quite a 
+  significant performance improvement.
+
+-----
+1.5.1. I can't use IBM's JDK: it doesn't have the Swing classes
+
+You are using an old version of GZigZag.  Current CVS versions and
+snapshots do not require Swing.
+
+-----
+1.9. I want to report a bug; how do I do that?
+
+There are instructions about this in http://www.gzigzag.org/bugs.html .
+
+-----
+2. How is the Java code structured?
+
+ZZCell and ZZSpace are the center of it all. Start from there and
+also ZZDimension, ZZDimSpace, ZZLocalDimension, ZZPersistentDimension,
+ZZPersistentDimSpace ...
+These latter ones are still a bit new and finding their places.
+
+-----
+3. Why is the ZZEventQueue not called / what is ZZObs / ... ?
+
+Legacy. It's currently supplanted by the ZZUpdateManager for view updates
+but may be revived later.
+
+-----
+4. What is the saved file format?
+
+See the Java/storage/ and Java/media subdirectories of the source
+tree, especially storage/Recs.java, storage/ZZPersistentDimSpace.java
+and media/StringScroll.java.
+
+-----
+5. Will my files be upwards compatible?
+
+No: the format will change soon. However, you can dump the space into XML
+(will be explained later) and restore it to the new file type.
+
+-----
+6. Are there any coding standards?
+
+See the file CODING in CVS.
+
+-----
+7. Do you accept patches?
+
+Yes, we do, but it helps if you consult with us first to make sure your
+intended change is in a reasonable direction. Much functionality should go
+into the Modules/ as well.
+
+diff -u (unified diff) is preferred.
+
+
+-----
+8. What are the advantages of the new Java version over the old Perl version?
+
+- Graphics. You just need to see the vanishing view to see why it's important.
+And that's just the beginning.
+
+- Active development.
+
+-----
+9. What are the disadvantages of the new Java version over the old Perl version?
+
+- Ted's own keystrokes do not yet work (to be fixed soon)
+
+
+
+=============================================================
+Section III: Questions specific to the Perl version
+
+1. Wasn't there a Perl version or something?
+
+Yes, written by Andrew Pam and others.
+
+-----
+2. Are the files from the Perl version compatible with the new Java version?
+
+No.
+
+-----
+3. Is it possible to import files from the Perl version to the new Java version?
+
+Not yet, but soon. Only needs a short Perl script to read the DB_File from
+the Perl version and write the corresponding XML code and then you can import
+it.

Documentation/Gentle_Introduction/Makefile

@@ -0,0 +1,19 @@
+all: gi.html gi-ns4.html
+# zzgentle.tex
+zzgentle.dvi: zzgentle.tex
+	pic -t <$*.tex >$*.tex
+	latex $*
+	cat $*.dvi >$*.dvi
+ps: zzgentle.ps
+
+# DIAGRAMS=linkorder.png beamorder.png
+DIAGRAMS=../wmlinc/article.wml
+
+gi.html: gi.wml $(DIAGRAMS)
+
+gi-ns4.html: gi.wml $(DIAGRAMS)
+
+include ../lib.mk
+
+
+

Documentation/Gentle_Introduction/README

@@ -0,0 +1 @@
+Requires latex and the xypic package for latex.

Documentation/Gentle_Introduction/gi.wml

@@ -0,0 +1,586 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+   "http://www.w3.org/TR/html4/strict.dtd"> 
+<!--
+	NOTE! This file uses WML 2.0.1
+
+	PLEASE PLEASE PLEASE don't edit .HTML. Edit .WML!!!! Actually,
+	it's more important for you since your changes will be LOST FOREVER
+	if you edit the .HTML files.
+ -->
+
+<html>
+ <head>
+  <title>A Gentle Introduction to Ted Nelson's ZigZag Structure</title>
+#include '../wmlinc/article.wml'
+ </head>
+ <body>
+{: [[s/(?<!>)\b(d\.+\w+)/<code>\1<\/code>/g]]
+<H1>A Gentle Introduction to Ted Nelson's ZigZag Structure</H1>
+<pre>$Id: gi.wml,v 1.4 2000/10/21 13:45:30 tjl Exp $</pre>
+<grid layout=3x3 spacing=20>
+ <cell> <b>Tuomas Lukka</b> <br>
+ 	<code>lukka@iki.fi</code><br>
+ </cell>
+</grid>
+
+<toc>
+
+<p>
+This document provides a short introduction to the abstract ZigZag
+structure and gives some pointers for designing structures for various
+applitudes. Unlike most of the other documentation related to GZigZag,
+this document is more about the abstract structure, not this one particular
+implementation.
+
+<p>
+This introduction, even though it is short, is still
+rather technical and detailed
+and therefore the even gentler manuscript "GZigZag: a platform for
+Cybertext Experiments" is recommended to be read before this document.
+
+<p>
+This is work-in-progress: if there are any unclear parts, feel
+free to ask me to clarify things.
+
+<warn>
+
+<h2>Introduction</h2>
+
+<p>
+The best words I've heard to describe the ZigZag structure
+are "hyperstructure kit". It is a set of tools or primitives for
+building hyperstructures.
+ZigZag was invented by Ted Nelson and is currently being implemented
+as a prototype at the University of Jyväskylä under the direction of
+the author.
+The purpose of this document is to introduce
+the reader to the ZigZag structure and some example applications of
+it. 
+
+<p>
+This document was written using material and ideas from 
+documents by and discussions with Ted Nelson,
+but also contains original ideas and material.
+
+<p>
+See also the glossary of ZigZag terminology in XXX.
+
+<h2>Basics</h2>
+
+<p>
+To arrive at ZigZag from a general perspective, consider the problem
+of storing and visualizing information in a structure.
+Now, we naturally need some kind of ``atoms'', i.e.~indivisible 
+pieces of information --- let's make an atom connected to a piece of text
+as the information it carries. Now, atoms should be connected to each other.
+Consider the two principles: 1) all connections must be two-directional
+and 2) to preserve visualizability, no cell should have an enormous number
+of connections. There are of course several different ways of realizing
+these principles but ZigZag is a particularly simple one.
+
+<p>
+ZigZag is a paradigm for manipulating data and devices, a platform
+if you may, in some way like UNIX. In UNIX (at least originally), everything
+is a file. Whether it is really a printer or the console or a network
+connection doesn't matter: the same basic operations (or at least 
+a subset of
+them) is available. ZigZag is quite similar: everything is a cell and
+connections between the cells. However, the structure set up by ZigZag is
+far richer than a hierarchical file system, allowing more interconnectivity
+between related information.
+
+<p>
+All data in ZigZag consists of <dfn>cells</dfn>. 
+A cell can contain e.g. text, an image
+or something like that --- basically, a unit of data.
+It does not matter how the content is stored; simply
+think of a cell as a little
+bit of data that has no significant internal structure (except of course the 
+sequence for text, the places of the pixels for an image etc).
+
+FIGURE
+
+<figure img="" width="">
+</figure>
+
+<p>
+The cells are the primitives of the structure and the structure is formed
+by connecting cells to each other through <dfn>dimensions</dfn>.
+In each dimension, each cell can have one positive and one negative 
+neighbour. This means that all connections between cells are
+two-directional: we speak of being neighbour to, or connected to,
+not of linking to since linking nowadays means one-directional HTML-like
+links.
+The different dimensions are denoted by names, such as d.1 or d.clone.
+
+<p>
+Now, if we have two dimensions and the cells are connected in a regular
+lattice, then this corresponds to a normal spreadsheet. However, no
+restriction is placed on which positive and negative ends are connected
+together - this is why this is called the ZigZag <em>structure</em>.  All kinds
+of structures are possible: loops, M\oe bius strips, spheres etc.
+The kind of structure to choose for your application is up to your
+imagination.
+
+<p>
+However, locally, from the perspective of one or two cells, this will
+still look like the spreadsheet: each cell has its neighbours and
+you go from it to one direction and then turn around and come back in
+the opposite direction, you end up in the same cell.  So locally this
+structure is logical and simple --- like a spreadsheet --- but globally
+it is paradoxical: you can just keep going into one direction and 
+arrive back where
+you came from, for example, or you can go left, down, right and up,
+and
+{\em not} come back where you started from in the end.
+This property gives more <em>room</em> in ZigZag for putting things
+in than a spreadsheet has, for instance.
+
+<p>
+One good way of visualizing this kind of structure is to think a
+device commonly found in science fiction books and films: a hallway
+with several doors. One door leads to a desert, and another to the
+antarctic. When you go through the door, you are in a different place
+but you can still walk back through the door, open the other door and
+walk through it.  At each moment separately, you are operating under
+the rules of three-dimensional space known to us but when you pass the
+door and realize that you don't see the other door from the other side,
+you know that you are in a paradoxical environment.
+
+<p>
+Another place to look for good, related visualizations, is the work
+of M.C.Escher, who has created many paradoxical spaces that would fit
+well with ZigZag. However, not all of his paintings work this way: in ZigZag,
+directions are global: up is the same ``up'' everywhere, unlike in some
+of Escher's work, so care has to be taken with this analogy.
+
+<p>
+A slightly different way of looking at the structure that may sometimes
+help thinking about it is to consider dimensions
+as {\em labeled lists} of cells.
+That is, instead of considering cells and connections, consider lists (each
+list labeled with a string) of 
+cells where the same cell may be on several lists (but only one
+with any given label).
+It is not difficult to see that this is exactly the same
+structure as above but viewed from a different angle: emphasizing the ranks
+instead of the single cell and its connections.
+
+<p>
+As an example of such a structure, consider a list of people and their
+birth years. It'd be quite natural to have first names, last names and 
+birth years in their own columns, each row being one person.
+If done e.g.~on a spreadsheet, you would have to settle
+for the global rectangular structure. However, with ZigZag you can
+do more interesting things such as have the first names in alphabetical
+order, the last names in alphabetical order and finally even the birth
+years in numerical order in their own colums. This is because the columns
+are independent of each other, bound together simply by having the rows
+going across them. Displaying such a structure can be done in several
+different ways.
+Also, it would then be easy to select subsets of the people on other dimensions,
+for example for people who are currently in the same class or whatever.
+
+<p>
+It is useful to be able to see the structure from both perspectives
+since this will both help to overcome the feeling of paradoxicality
+from the spreadsheet-like connective picture but also remember that
+the cells are important objects in the list picture.
+
+<h2>Comparing ZigZag with existing computer structures.</h2>
+
+<p>
+To put it coarsely, outside ZigZag there are three different kinds of
+structures in computers today: linear lists (and grids i.e.~lists of lists), 
+hierarchical trees and messes. That is really messes, not meshes. By 
+a mess, I mean any complicated data structure, usually with one-directional
+links to make things even more unmanageable.
+
+<p>
+The first two are inflexible, even with one-directional 
+hierarchy-crossing links
+such as symlinks in filesystems or XML IDs.
+The third always requires much
+programming and debugging to do and is often hard to visualize.
+
+<p>
+ZigZag offers a fundamental new kind of <em>structure</em> where encoding
+new structures is simple because the coherence of the underlying
+simple flexible structure is guaranteed.
+At first it may seem strange that a structure that restricts the
+number of connections from each cell can be generic but this simple
+restriction is what brings about the coherence of ZigZag. 
+In the sections below you'll see how this restriction does not prevent
+any structure from being represented using ZigZag but it enables several
+clever visualizations.
+
+<p>
+Among other things,
+ZigZag guarantees that there are no dangling pointers: all links are 
+two-directional. You can always find which cells refer to a given cell.
+
+<p>
+One interesting thing to note
+about ZigZag and existing structures,
+the importance of which I really only realized while doing a demo at Nokia
+is simply that by using different dimensions, ZigZag allows you to 
+arrange the <em>same</em> things into <em>different</em> traditional
+structures. So you can have the same cells in a tree along two
+dimensions (as you'll see below, trees are easiest done using two
+dimensions, one to go from the parent to the first child and the other
+to move along siblings), a list along another dimension and a table
+along two other dimensions. And possibly another tree in yet two more
+dimensions, if desired.
+If you use relcells (see below)
+you can even put the same things (this time, not cells: you do have to do a step of indirection)
+into different structures along the 
+<em>same</em> dimensions.
+
+<h2>Viewing</h2>
+
+<p>
+Now that the structure is defined, we have to be able to view and edit
+it on the computer somehow. Of course, we <em>could</em> just put this
+structure in a text file and edit it by naming cells with numbers and
+links by naming the cell numbers but this would lose the visuality
+inherent in the design.
+
+<p>
+There are <strong>many</strong> variations to the theme of viewing
+ZigZag structures. Views range from generic to specific views.
+Generic views are designed to be useful with a wide range of structures
+and usually therefore show only a small number of dimensions
+or a small number of steps along each dimension.
+Specific views on the other hand are free to do anything that
+suits the application at hand. 
+
+<p>
+Specific views are related to <dfn>applitudes</dfn>, explained below
+in more detail.
+
+<p>
+In this section, we look at the structure of several generic views.
+Before going to the views themselves, let us first define some terms:
+the <dfn>raster</dfn> and the <dfn>view</dfn>.
+A raster is a way of selecting cells from the structure. 
+A view is a way of placing the selected cells on the screen.
+
+<p>
+In order to look clear to the human observer, visual cues about the
+structure are vital.  All neighbouring cells that lie next to each other
+should be connected with a line, and all cells that have neighbours
+that were not displayed because of the raster should have e.g. half of a
+connecting line, disappearing underneath the other cell in some visual
+fashion to show this.  Also, when moving in the structure so that the
+part of
+
+
+	<h3>2D rectangular views</h3>
+
+	<p>
+	The 2D rectangular views are characterized by placing the 
+	cells in a spreadsheet-like rectangular grid on the screen.
+	Even here, there are many different possible
+	rasters for choosing which cells to place where, since
+	a general ZigZag structure will not fit a rectangular grid
+	and parts have to be clipped out.
+	Note that the 2D here refers to the two-dimensionality of the
+	rectangular grid, not that there need to be only two dimensions
+	of the ZigZag structure showing. Usually we only have two
+	in these views but as we see below, this is not a requirement.
+
+	<p>
+	The two simplest rasters useful for the rectangular views
+	are the row and column rasters, which are actually
+	the same raster but placed on the screen rotated 90 degrees
+	from each other.
+	These rasters are genuinely two-dimensional: they only
+	use two dimensions in the ZigZag structure to find cells
+	to display.
+
+	<p>
+	The row/column raster
+	starts from the cursor and moves along one ZigZag dimension
+	and place cells on the center column/row of the grid.
+	After that column/row is full, the raster starts from
+	the cells placed and from each, moves along the other 
+	dimension and places the cells found along the other
+	dimension there.
+
+	<p>
+	These rasters are called <dfn>hard rasters</dfn>: 
+	the arrangement of cells is fixed so that there is
+	only one possible path from the cursor to a cell to be
+	placed in a given position on the screen. If there is no 
+	cell in the structure along such a path, then that
+	location is left empty.
+
+	<p>
+	The converse of hard rasters are the <dfn>soft rasters</dfn>
+	where there can be several different paths for 
+	each cell of the on-screen grid.
+	The point of soft rasters is that since ZigZag structures are
+	often relatively sparse in terms of connections, the
+	hard row and column rasters may show relatively few cells at
+	a time. Soft rasters are able to show more of the structure
+	at the same time.
+
+	<p>
+	There are many different ways to define soft rasters for 
+	the rectangular grid. One fairly useful way is to specify
+	the soft raster so that all the cells that a certain hard
+	raster would show are shown, but additionally, if there
+	is space left, more cells are shown along the dimensions.
+
+
+	<h3>Vanishing view</h3>
+
+	<p>
+	The vanishing view looks a little like the hard row/column
+	raster above but is in fact a completely different beast.
+	The raster for a vanishing view consists of all the cells
+	within a given 2- or 3-dimensional Manhattan distance
+	from the cursor (a Manhattan distance simply means the number
+	of connections in any direction to get from one cell to another).
+
+	<p>
+	These cells are then placed on screen starting with the center
+	cell and reducing the cell size as the distance from the cursor
+	grows. This causes cells that would be in the same slot
+	in the rectangular grid to be plotted apart from each other.
+
+	<p>
+	This could easily be generalized to more than three dimensions.
+
+	<h3>Compass view</h3>
+
+	<p>
+	The previous views have dealt with a few dimensions but several
+	steps along those dimensions. The compass
+
+	<h3>Multicentric views</h3>
+
+	<p>
+	XXX
+
+	<h3>Text view</h3>
+	
+	<p>
+	One simple view that can be easily overlooked is to simply
+	take a rank of cells and show their texts appended to each other.
+
+<h2>Applitudes</h2>
+
+<p>
+To distinguish itself from the traditional, monolithic applications,
+ZigZag uses the term <em>applitude</em> for a "zone of functionality".
+The difference between applications and applitudes is the interconnectivity:
+whereas conventional, monolithic applications are used to having all data
+in their own files, applitudes can easily share cells and simply use
+their own, orthogonal dimensions to connect cells.
+
+<p>
+The differences caused by this simple shift are enormous: instead
+of a selection of monolithic blocks, the contents of the computer can 
+become an interconnected, organic whole.
+Everything connected to a particular person, for example, is
+connected to the same cell, whether in the email applitude, the calendar,
+the collection of documents or anything. 
+
+
+<h2>Designing structures</h2>
+
+<p>
+In this section, we'll go through some commonly occurring 
+structural patterns in ZigZag. These can be thought of as being
+analogous to Design Patterns in Object-Oriented Programming.
+The patterns here are not formalized as far as OO design patterns
+but carrying out such a treatment would not be difficult.
+
+<p>
+As you will see, there are several different ways of encoding
+the same conceptual structure in ZigZag. The choice between
+using a different dimension or a rank of clones, for example.
+These alternative codings resemble in some way one of XML's
+similar ambiguities: for example whether to code something as an attribute
+or as a contained text-only element. 
+
+<p>
+It is important to understand the difference
+between the low-level structure and the implied, higher-level
+structure. Single cells and single connections are building
+blocks, not necessarily complete entities by themselves.
+	<h3>Cloning</h3>
+
+	<p>
+	One of the basic structural mechanisms in ZigZag is
+	cloning, i.e. connecting cells on d.clone to imply that
+	they are somehow the same as the root clone, i.e. negend
+	of d.clone.
+	
+	<p>
+	This mechanism is coupled with the cell content:
+	the contents of all clones is the same as the contents
+	of the root clone, and editing a clone edits the root clone.
+
+	<p>
+	XXX
+
+	<p>
+	There are alternatives to cloning, and in many cases they
+	may be preferable. 
+	For instance, in a calendar applitude it would be possible
+	to clone the cells for persons into the structures
+	representing meetings but a possibly preferable approach
+	would be to use an applitude-specific dimension for this.
+	The reason is that then this dimension would always lead
+	to predictable structure and the applitude could
+	easily give interesting visualizations of the meetings
+	a person participated or will participate in.
+
+	<p>
+	This is a fairly unsettled question. With more experience
+	in designing different applitudes we will be able to tell easier when
+	clones are appropriate and when special dimensions are better.
+
+	<h3>Arrangement along a dimension</h3>
+
+	<p>
+	Sometimes, there is a good, unique way of arranging cells along a
+	dimension, e.g. alphabetical order. However, sometimes there is not,
+	or there are two different orders you'd like to have.
+
+	<p>
+	This may seem like a difficult problem but actually, if all
+	but one of the desired orders are easy to determine from the
+	neighbours of the cells, then there is no problem at all: instead
+	of expressing it directly in the structure, those orderings that
+	are easy to construct algorithmically should be delegated to
+	the view (as of yet, there are no viewers capable of this but
+	they are under construction).
+
+	<p>
+	Another alternative (that does not currently work) will be
+	to thread the cells through several dimensions, most of which
+	are implicit: for example, an implicit d.1-alphabetic could
+	have the same ranks as d.1 but alphabetized. The implicit
+	dimensions would be read-only and be updated automatically
+	when the corresponding real dimensions changed.
+
+	<p>
+	If there is more than one order that is not easily determinable,
+	then using two dimensions or cloning becomes a thing to 
+	consider.
+
+	<h3>Many to one reference</h3>
+
+	<p>
+	Even though the structure only allows only 
+	two connections along each dimension, it
+	is possible for
+	many cells to refer to one in ZigZag.
+	This works by the way outlined above, by building
+	a higher-level
+	structure from the low-level building blocks of the cells
+	and connections.
+
+	<p>
+	There are of course
+	different ways for creating many to one reference,
+	but two main ones distinguish themselves.
+
+	<p>
+	If the cell referred is very different from the 
+	cells referring to it, then a single rank, where
+	the referred-to cell is the headcell is a good choice.
+	Clones, for example, work this way (see above).
+
+	<p>
+	If the referents can be of the same "type", then 
+	it becomes necessary to allow the cell referred to to
+	refer to another cell. In such case, a construction called
+	a <dfn>corner list</dfn> is used.
+	A corner list works by using two dimensions: 
+	the first one connects all the cells referring to a given
+	cell and the second one connects the referred-to cell 
+	to the headcell of that rank. 
+	There are two main variants: the empty-headed 
+	one where the headcell is
+	empty and the solid one where the headcell is one of the referring
+	cells. The insert and delete referring cells operations are
+	simpler for the empty-headed list since all referring
+	cells are in the same position but that configuration wastes
+	one cell.
+
+
+	<h3>Hierarchies</h3>
+
+	<p>
+	A hierarchy can be understood as a many-to-one reference
+	relation, with the children of a given cell being the
+	cells referring to it.
+
+	<p>
+	This would make a tree mapped as in the figure XXX.
+
+	<p>
+	It is good to remember that the same cells can be in
+	several different trees using different dimensions.
+
+	<h3>Relation cells</h3>
+
+	<p>
+	Relation cells (relcells) are a commonly occurring construct
+	in ZigZag.  Fundamentally, relcells exist to declare a relationship
+	between two cells or two groups of cells.
+
+	<p>
+	One example of a relcell would be the empty headcell in the
+	empty-headed version of the corner list above.
+	However, this is a fairly untypical example.
+
+	<p>
+	Typically, a relcell is on two or more ranks and implies
+	a relationship between the headcells of those ranks.
+	This way, each cell can have the same relationship to 
+	several other cells at the same time.
+
+	<p>
+	A good example of the use of a relation cell is
+	the genealogy applitude (pardon the obvious puns).
+	The idea is to connect all the siblings on one rank in the family
+	tree and married couples on another, but this leaves
+	open the question of representing the children born in the marriage.
+	This is solved by placing a relcell <em>between</em> the parents,
+	and hanging the sibling rank off that cell as the headcell.
+	This relcell then implies a parent-child relationship between
+	the cells connected to it..
+
+<h2>Example applitudes</h2>
+
+XXX
+
+<h2>The Cousin Problem</h2>
+
+	<p>
+	There is one important problem when dealing with data 
+	that has relations, which the author calls the "Cousin" problem.
+	Consider the genealogy applitude. 
+	Now, insert a new person, A, and then his cousin, B.
+	A moment's reflection will show that this is impossible
+	in the data structure explained above.
+
+	<p>
+	This is because in the human representation of concepts,
+	there is no hierarchy between mother, father, son, daughter and
+	cousin. There is no good way to pick just one way to represent
+	the information since the idea "B is A's cousin" is perfectly
+	valid, even without knowing whether it is on the mother's or
+	father's side.
+	
+:}
+</body>
+</html>
+<!--
+	vim: set syntax=html :
+-->

Documentation/Glossary/Makefile

@@ -0,0 +1,10 @@
+# DIAGRAMS=linkorder.png beamorder.png
+DIAGRAMS=../wmlinc/article.wml
+
+all : gl.html gl-ns4.html
+
+gl.html: gl.wml $(DIAGRAMS)
+
+gl-ns4.html: gl.wml $(DIAGRAMS)
+
+include ../lib.mk

Documentation/Glossary/gl.wml

@@ -0,0 +1,186 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+   "http://www.w3.org/TR/html4/strict.dtd"> 
+<!--
+	This is an article intended for the CyberText yearbook.
+
+	It is written in WML, which is close to HTML while providing 
+	some easier ways to create certain constructions, such as
+	the figure tag.
+
+	NOTE! This file uses WML 2.0.1
+
+	PLEASE PLEASE PLEASE don't edit .HTML. Edit .WML!!!! Actually,
+	it's more important for you since your changes will be LOST FOREVER
+	if you edit the .HTML files.
+ -->
+
+<html>
+ <head>
+  <title>GZigZag Glossary</title>
+
+#include '../wmlinc/article.wml'
+
+
+ </head>
+ <body>
+ <substdims>
+<H1>GZigZag Glossary</H1>
+<pre>$Id: gl.wml,v 1.3 2000/09/19 10:31:57 ajk Exp $</pre>
+<grid layout=3x3 spacing=20>
+ <cell> <b>Tuomas Lukka</b> <br>
+ 	<code>lukka@iki.fi</code><br>
+</grid>
+
+<p>
+This is a short glossary of terminology related to GZigZag.
+Only a short definition of each term is given, possibly with
+a reference to more material on the subject.
+
+<warn>
+
+<hr>
+<dl>
+	<dt>ZigZag structure / space
+	<dd>	A simple structure, based on <i>cells</i> and <i>dimensions</i>
+		which the user is able to easily shape into any desired
+		structure. All interrelated pieces of information can be
+		close to each other on some dimension.
+	<dt>cell
+	<dd>	The smallest unit of information in ZigZag.
+		A cell can contain a text string or 
+		a single span in a permascroll; the separation is
+		because a text string can be edited but a span can only
+		be lengthened or shortened: no characters can be 
+		inserted. Cells are connected to each other along
+		dimensions.
+	<dt>dimension
+	<dd>	Connecting cells along dimensions is what ZigZag is
+		about. Locally, dimensions work just like on a spreadsheet:
+		each cell can be connected to one cell in the positive
+		direction and to one cell in the negative direction 
+		along each dimension. However, there are no global constraints
+		between the dimensions.
+		
+	<dt>headcell
+	<dd>	The negend of a rank, <em>or</em>, for
+		circular ranks, a specially designated cell.
+		If a rank of cells has one "special" cell, then
+		it is usually the headcell.
+		
+
+	<dt>neighbour
+	<dd>	Cells that are connected along a dimension are
+		called each other's neighbours. Often, the term
+		posward or negward is used with this term as in
+		"the negward neighbour on d.cursor".
+
+	<dt>posward/negward
+	<dd>	In the positive/negative direction along a rank.
+
+	<dt>posend/negend
+	<dd>	As far as you can go negwards or poswards. 
+		Circular ranks have no ends.
+
+
+	<dt>rank
+	<dd>	A rank on a dimension D is simply a set of cells that are
+		connected to each other on D. A given cell can only
+		be on one rank on a given dimension.
+
+	<dt>raster
+	<dd>	A set of cells selected from the structure
+		by a set of rules, for visualization.
+		For example, the row and column raster select,
+		starting from the cursor,
+		a single rank in one dimension
+		an all ranks in another dimensions that 
+		intersect that rank.
+		The raster for the vanishing view selects all 
+		cells within a given radius of the cursor.
+
+	<dt>relcell, or relation cell
+	<dd>	A cell which exists not for its content but for 
+		expressing a relationship between other cells.
+		For example, the cell between a father and mother
+		in the family tree demo is a relcell.
+
+	<dt>row/column
+	<dd>	These words simply correspond to ranks
+		<em>being viewed</em> horizontally/vertically.
+		They do not mean anything in the abstract structure,
+		but only in the visualizations.
+
+	<dt>view
+	<dd>	A way of placing the cells in a particular
+		raster on the screen.
+
+</dl>
+<hr>
+<dl>
+
+	<dt>FloatingWorld
+	<dd>	Ted Nelson's design built on top of ZigZag structure,
+		based on <i>flobs</i>.
+	<dt>flob
+	<dd>	A multi-dimensional flying object. That is, an entity
+		representing something that may have any number of 
+		<i>flob coordinates</i>. For example, an email's sender is one
+		flob coordinate, its subject another.
+
+</dl>
+<hr>
+<dl>
+
+
+	<dt>Xanadu88
+	<dd>	A hypertext system, finished in 1988, which works by
+		stable <i>fluid media</i> content instead of URL-like pointers.
+	<dt>fluid media
+	<dd>	Any media types that can be subdivided.
+		Text, audio, video, images.
+	<dt>permascroll
+	<dd>	A storage philosophy for fluid media where
+		each smallest unit (e.g. character of text)
+		is assigned a permanent identifier when
+		it first enters the system. Of course, 
+		references to the smallest units usually happen
+		through <i>span</i>s for efficiency.
+	<dt>span
+	<dd>	A (reference to a) contiguous section of the permascroll.
+	<dt>vstream
+	<dd>	A list of spans that describe a virtual stream of
+	    	fluid media. A "document" or one version of a document.
+		Modifying a document does not modify the permascroll, except
+		by appending new inserted characters. Instead, the spans
+		of the vstream are modified: split apart, new spans
+		inserted etc.
+	<dt>transclusion
+	<dd>	The inclusion of the same material in a permascroll in 
+	    	two different documents. One of the fundamentals of the Xanadu88
+		model is that it is efficient to search for transclusions
+		of a given span.
+	<dt>transpointing windows
+	<dd>	Windows on a computer screen that show the connections or 
+		transclusions between each other.
+
+	<dt>transcopyright
+	<dd>	A copyright scheme where the copyright holder 
+		grants the public a permission to refer to any
+		portion of a given document and publishes the document
+		in a permanent location.
+		This way, anyone can quote the document by referring
+		to it and the reader's browser will then go to the
+		originator's server for the original material so that
+		a micropayment can be made to the original author
+		of the material.
+</dl>
+
+<hr>
+ </substdims>
+ </body>
+</html>
+
+<!--
+	vim: set syntax=html :
+-->
+

Documentation/Interfacing/Makefile

@@ -0,0 +1,6 @@
+int.dvi: int.ptex
+	gpic -t <int.ptex >int.tex
+	latex int.tex
+ps: int.ps
+int.ps: int.dvi
+	dvips int

Documentation/Interfacing/int.ptex

@@ -0,0 +1,141 @@
+% MAKE SURE YOU EDIT THE RIGHT FILE, int.ptex and not the int.tex
+% file where gpic has already expanded things.
+\documentclass{article}
+
+\usepackage{rcs}
+\RCS $Date: 1999/12/23 01:53:35 $
+\RCS $Revision: 1.3 $
+\date{Rev.\RCSRevision~~\RCSDate}
+
+\title{Interfacing ZigZag with ``normal'' programs}
+\author{Tuomas J.~Lukka}
+\begin{document}
+\maketitle
+
+\def\zz{ZigZag}
+
+\section{Introduction}
+
+\zz\ defines a coherent universe of cells and things that happen
+when cells are modified and connected to each other.
+However, since the computer and windowing system underneath don't know
+anything about \zz, there is a level on which the \zz\ abstraction
+and ``normal'' programs in e.g.~Java meet, so that \zz\ can be implemented
+in e.g.~Java.
+Because \zz\ is so different from our usual programming concepts,
+an interface like this is not trivial to design correctly and
+efficiently.
+
+While the basic operations are simple, i.e.~get neighbour, connect,
+create new cell etc., the handling of the interface in a coherent way
+on both sides is not simple.
+As an example of the difficulty, consider 
+keeping a list of some attributes that you want the screen to show.
+It doesn't matter what these are attributes of, or how they are shown.
+We are concerned with the list itself. 
+
+\section{Model-View-Controller}
+
+When programming with \zz, the MVC (Model-View-Controller) representation
+is a useful abstraction, the point being that all the relevant information
+is kept inside the \zz\ space with many different views of the same
+data being then  possible.
+
+Let us then expand on the list-of-attributes problem.
+The natural representation for a list of attributes
+is rank along some dimension
+in the \zz\ space, beginning at some designated cell. 
+Having the list in the \zz\ space gives the system the kind of
+programmability and coherence which you won't find anywhere else.
+However, this programmability and coherence does not come entirely 
+free. The trouble is when your e.g.~Java code which actually handles
+the drawing on screen wants to use the list.
+
+Just reading the list with the above operations is easy, you just
+start at the designated cell and work your way through the list.
+The trouble starts when the user modifies the list. At that point,
+the user's expectation is that the display will change accordingly.
+So your program should realize that the list changed.
+
+This can be handled through callback routines but the problem is
+keeping the callbacks up to date as well and handling the overzealous
+callbacking with grace (e.g. if the user makes many modifications and
+some while the system is busy rerendering the graph). 
+
+\section{Synchronization}
+
+When several concurrent processes or threads are active on the 
+same \zz\ space, care is necessary to avoid race conditions (as
+in all other programming with concurrent streams of execution).
+
+
+
+\section{A proposed solution: {\tt d.watchers} and {\tt d..watching}}
+
+As seems to happen often with \zz, the problems can be partially
+solved by moving the system to \zz\ space. 
+So, why not have two dimensions (see the section on relcells 
+in the Gentle Introduction) showing the relationship between 
+nodes representing observers and nodes representing watchers?
+
+This simplifies things because there will be one cell on the \zz\ side
+representing the Java object which is observing a group of cells.
+The ``A observes B'' relation is encoded into the \zz\ structure
+as in Fig.~\ref{fig-enc}
+and makes it possible visualize and {\em debug} what is going on. 
+
+\begin{figure}
+\caption{Encoding watching relations in the \zz\ structure.
+Watcher A watches both cells 1 and 2 and watcher A only watches 
+cell 1.}
+.PS
+A: box "Watcher B" height 0.25
+arrow "\tt d..watching" ""
+box "" same
+up
+move to last box.n
+line <- "~\tt d.watchers" ljust
+R1: box "" same
+right
+move to last box.e
+arrow
+R2: box "" same
+move to R1.w
+left
+line <-
+B: box "Watcher A" same
+move to R1.n
+up
+line <-
+box "Cell 1" same
+move to R2.n
+line <-
+box "Cell 2" same
+.PE
+\centerline{\raise 1em\box\graph}
+\end{figure}
+
+Also, the relcells can be put to another use beyond just showing
+that there is a relation
+in this design: they show the {\em kind} of watching relation, 
+i.e.~contain a list
+of things that the other cell is observing about the observed cell,
+such as the content or the connections along some subset of dimensions.
+This makes it easier to avoid unnecessary work in the list example
+if someone wants to comment (along {\tt d.comment}) on one of
+the cells in the list.
+
+Even more pleasantly, this design will fit in nicely with Clang:
+the cell which is observing can just as well be a Clang script.
+
+\section{Designing \zz-code interfaces}
+
+
+
+
+
+
+\end{document}
+
+%
+% vim: set syntax=tex :

Documentation/Makefile

@@ -0,0 +1,39 @@
+all:
+	echo "Use a target"
+
+docdirs=ApplitudeWriters Clang_Design CyberText DesignProblems Gentle_Introduction Glossary Spec UsersGuide Nile
+
+distdocs:
+	set -e ; for d in $(docdirs); do $(MAKE) -C $$d all ; done
+
+dist: distdir=docdisttree
+dist: distdocs
+	rm -rf $(distdir)
+	mkdir $(distdir)
+	ln FAQ $(distdir)
+	ln index.html $(distdir)
+	set -e; for d in $(docdirs); \
+	        do \
+	            echo -n "mkdir $(distdir)/$$d...";\
+	            mkdir "$(distdir)/$$d"; \
+	            echo "done."; \
+	            files=`find $$d -name \*.html -o -name \*.png`;\
+	            echo "Copying `echo $$files` to $(distdir)/$$d..."; \
+	            ln -f $$files $(distdir)/$$d; \
+	            echo "done."; \
+	        done
+
+ps:
+	(cd CellScroll; make ps)
+	(cd Clang_Design; make ps)
+	(cd Gentle_Introduction; make ps)
+	(cd Interfacing; make ps)
+	(cd Spec; make ps)
+
+# Special target for Tjl only ;)
+mvps: ps
+	scp */*.ps tjl@gzigzag.sourceforge.net:/home/groups/gzigzag/www/ps/
+cleanps:
+	rm -f */*.ps
+clean: cleanps
+	rm -f */*.dvi */*.log */*.xyc */*.pdf

Documentation/Math/Makefile

@@ -0,0 +1,3 @@
+all : math.dvi math.ps
+
+include ../lib.mk

Documentation/Math/ajk-scribbles.tex

@@ -0,0 +1,60 @@
+\documentclass{article}
+
+\usepackage{bbm}
+\usepackage{amsmath}
+
+\newcommand{\N}{\mathbbm{N}}
+
+\newtheorem{Def}{Definition}
+\newtheorem{The}{Theorem}[Def]
+
+\DeclareMathOperator{\Dom}{Dom}
+\newcommand{\Dim}[1]{\tilde{#1}}
+
+\begin{document}
+
+Note: we assume here that dimensions are cells instead of strings.
+
+\begin{Def}[space]
+A ZigZag space is the triplet $Z = (X, c, C)$ where $X$ is the set of
+cells, $c : X \rightarrow \Sigma^*$ is the cell content mapping
+and $C \subset X^3$ is the set of connections, if the following hold:
+%
+\begin{enumerate}
+%
+\item If $(d, e, f) \in C$ and $(d, e', f) \in C$ then $e = e'$.
+%
+\item If $(d, e, f) \in C$ and $(d, e, f') \in C$ then $f = f'$.
+%
+\end{enumerate}
+\end{Def}
+
+\begin{Def}[subspace]
+A ZigZag space $Z' = (X', c', C')$ is a subspace of another ZigZag
+space $Z = (X, c, C)$ if the following hold:
+%
+\begin{enumerate}
+%
+\item $X' \subset X$
+%
+\item $c'(x) = c(x)$ for every $x \in X'$.
+%
+\item $C' \subset C$
+%
+\end{enumerate}
+\end{Def}
+
+\begin{The}
+  Let $Z = (X, c, C)$ be a ZigZag space.  For every $d \in X$, there
+  exists a maximal $X' \subset X$ and a unique $\Dim{d} : X'
+  \rightarrow X$ such that for every $x \in X'$ it holds that $(d, x,
+  \Dim{d}(x)) \in C$.  Additionally, $\Dim{d}$ is an injection.
+\end{The}
+
+\begin{Def}[clone dimension]
+  Let $Z = (X, c, C)$ be a ZigZag space.  We say that $d \in X$ is a
+  clone dimension if, for every $x \in \Dom d$ it holds that $c(x) =
+  c(\Dim{d}(x))$.
+\end{Def}
+
+\end{document}

Documentation/Math/math.ptex

@@ -0,0 +1,110 @@
+% Emacs, note: this is a -*- LaTeX -*- file.
+% MAKE SURE YOU EDIT THE RIGHT FILE, math.ptex and not the math.tex
+% file where gpic has already expanded things.
+\documentclass{article}
+
+\usepackage{rcs}
+\RCS $Date: 2000/07/18 05:21:50 $
+\RCS $Revision: 1.3 $
+\date{Rev.\RCSRevision~~\RCSDate}
+
+\usepackage{amsmath}
+
+\title{Mathematics of ZigZag}
+\author{Tuomas J.~Lukka}
+\begin{document}
+\maketitle
+
+\newtheorem{theorem}{Definition}[section]
+\newtheorem{definition}[theorem]{Definition}
+
+\section{Introduction}
+
+The purpose of this document is to look at ZigZag from a
+mathematical perspective.
+
+It is slowly becoming more and more obvious that this type of analysis
+can help us understand some of the conceptually less clear parts of ZigZag
+and why they are conceptually less clear.
+
+\section{Tumblers}
+
+\section{Definition of a ZigZag space}
+
+\begin{definition}
+% A ZigZag space $Z$ is the tuple $(C, d, t)$ of the set of cells $C$,
+% a mapping $d$ from strings to bijections between subsets of $C$, 
+% and a mapping $t$ from cells to cell contents
+% (either permascroll spans as tumbler addresses or strings)
+A ZigZag space $Z$ is the tuple $(C, d, t)$ of the set of cells $C$, a
+mapping $d$ from strings to the set \( D := \{ \, f\colon $C'$
+\longrightarrow $C''$ \mid \text{$f$ is bijective and } C', C''
+\subset C \, \} \) and a mapping $t$ from cells to the set of all
+possible cell content (permascroll spans as tumbler addresses or
+strings).
+\end{definition}
+
+Now, special dimensions can be defined simply as restrictions on 
+the space; for instance, as predicates:
+\begin{definition}
+The ZZspace $Z$ has a clone-dimension $d_0$ iff
+for all cells $c$ for which $d(d_0)(c)$ exists, $t(d(d_0)(c)) = t(c)$.
+\end{definition}
+
+Likewise, we can define a versioning operation:
+\begin{definition}
+A ZZ operation $o: Z \rightarrow Z'$ is versioning
+if ... XXX
+\end{definition}
+
+
+\section{Solving real problems}
+
+\subsection{Slice spaces}
+
+It is possible to highlight some problems related to defining operations
+and combinations of spaces with this type of analysis. One observation
+made early on in the coding was that encapsulation makes it complicated
+to define operations on e.g.~slice spaces (spaces that consist of a 
+combination of several spaces). For example, in $C = f(A,B)$ the ZZspace
+is $C$ a slice space if it contains cells corresponding to most cells 
+of $A$ and $B$ (excluding {\em preflets}, i.e. cells whose meaning is to
+specify for $f$ which cells are to be connected between $A$ and $B$).
+
+The forwards transform is simple: $C = f(A,B)$ as above. 
+However, problems begin to appear when we consider that normally
+performing an operation functionally: $A' = \Omega(A)$ causes $A'$ to be
+saved on the disk to replace $A$. $C' = \Omega(C)$ cannot do the same
+as simply because we would like to trace the chain to change $A$ and $B$,
+obtaining $(A', B') = f^{-1}(\Omega(f(A,B)))$. This can naturally be quite
+complicated. Most combination functions $f$ used in reality are nice but still
+this causes a pronounced difficulty in coding the usual operations
+(new cell, etc) on slice spaces if starting from this perspective.
+
+Thus, the conceptually simplest way forwards might be defining a whole
+new kind of mathematical object, a slice space, which has its own 
+operations that naturally distribute to the next level.
+After this it is simple to define performance enhancements by caching parts
+of the next level space but the conceptual simplicity of directly modifying
+only the underlying representation (instead of e.g.~the representation {\em and}
+a cache) is appealing.
+
+\begin{definition}
+A Slice space $S$ is a 
+tuple $(Z_0, s)$ where $Z_0$ is the slice 0, i.e.~the root space,
+and $s$ is a mapping from strings to ZigZag spaces 
+\end{definition}
+
+\begin{definition}
+A slice composition function 
+$f_c$ is a mapping
+$S \rightarrow Z$
+from a slice space to a ZigZag space (the composition function).
+\end{definition}
+
+
+
+\end{document}
+
+
+

Documentation/Mediaserver/mediaserver.tex

@@ -0,0 +1,387 @@
+% This is a -*- LaTeX -*- file.
+\documentclass[a4paper]{article}
+
+\newcommand{\ra}{\ensuremath{\rightarrow}}
+
+\ifx\dontdraft\undefined
+%Draft
+\newcommand{\marginaali}[1]{\marginpar{#1}}
+
+\setlength{\marginparwidth}{3cm}
+\setlength{\textwidth}{13cm}
+\setlength{\oddsidemargin}{1.3cm}
+\else
+%Non-draft
+\newcommand{\marginaali}[1]{}
+\linespread{1.6}
+\fi
+
+\newcommand{\nakki}[1]{\marginaali{\textbf{\small Nakki: #1}}}
+\newcommand{\ajk}[1]{\marginaali{\small ajk: #1}}
+\newcommand{\tjl}[1]{\marginaali{\small tjl: #1}}
+
+\begin{document}
+
+\title{GZigZag mediaserver (to be renamed!) design}
+\author{Tuomas J.\ Lukka \and Antti-Juhani Kaijanaho}
+\date{2001}
+
+\maketitle
+
+\begin{abstract}
+The purpose of the mediaserver is to implement 
+the Xanadu permascroll model
+in an easy-to-use encapsulated fashion.
+
+The mediaserver incorporates both peer-to-peer and 
+client-server transfer of data.
+
+This ties in with Ted's other projects, and the intent
+is to produce a simple but powerful system completely independent
+of GZigZag (GZigZag is on a higher level and uses this as a library).
+(The source code is currently in the GZigZag repository but
+we might make a new project out of it at some point)
+\end{abstract}
+
+\begin{verbatim}
+$Id: mediaserver.tex,v 1.12 2001/04/03 11:23:58 ajk Exp $
+\end{verbatim}
+
+
+\section{Intro}
+
+The Xanadu media model is based on attaching a permanent identifier
+to each piece of fluid media (e.g. text, audio) entering the system.
+This arrangement adds a level of indirection to media access, allowing
+content linkage, version comparison of documents composited from
+spans of fluid media, and automatic sharing of data between copies.
+
+Additionally, the Xanadu media model incorporates micropayments:
+when requesting a
+
+The gzz mediaserver is an implementation of these ideas\ldots
+
+Somewhat like freenet, but encryption is not the point here, point
+is media sharing, caching, replication and access.
+
+\subsection{Digital Rights Management versus Fair Use}
+
+\begin{itemize}
+\item support copying of cached content between the user's machines, but
+  no large-scale copying without repayment to content originator
+
+\item voluntary compliance
+
+\item testing of compliance by requests
+
+\item give people possibility of doing the right thing
+
+\item Asserting copyright \ra\ revocation?
+  The infringer is the one granting access to the material, not the user!
+\end{itemize}
+
+\subsection{For Gzigzag}
+
+If we want to include a piece of audio into a ZZ space and then copy
+the space for experiment / backup, the audio will also be copied, taking
+up space. Creating a simple black-box stable media server will remove
+this problem.
+
+Also, mirroring data between machines is easier.
+
+Eventually, cells to be stored as change packets in the mediaserver.
+
+
+\subsection{Local and Cached Material}
+
+All material is divided into local and cached material. Cached
+material may be removed from the system at any time without notice.
+Removing local material requires special procedures. Material may be
+changed from local to cached but not the other way around.\ajk{I'd
+  rather have permanent and transient material; that way someone who
+  absolutely wants to keep a local copy of a remote datum can do so.}
+
+
+\subsection{Quality Levels}
+
+It is quite simple to expand this approach to support different
+qualities for sounds and images; loading the given image at a lower
+quality may be more efficient especially over a slow network, likewise
+for sound.
+
+\section{Functionality}
+
+\begin{itemize}    
+    \item communicate over network with other instances of mediaserver
+    \item cache media locally
+    \item manage local store, serve published portions over network
+    \item return given span of media
+    \item record media, tag addresses / spans
+    \item append text, char by char, efficiently
+    \item manage unique ids through prefix-for-each-server.\ajk{I have
+        a better idea: delegateable infinite id space.  Elaborated
+        below.}
+    \item ID conflict is a fatally serious issue - exchange CRCs 
+          occasionally for random mutually shared pieces just to check.
+\end{itemize}
+
+\subsection{Basic interface}
+
+Recorder / Player? See Modules/sound/*.java
+
+\begin{verbatim}
+interface MediaServer {
+    /** Load the media denoted by the span, or null if not loadable.
+     */
+    Media getMedia(Span s);
+
+    /** Load the media denoted by the span asynchronously
+     * and return
+     * an asynchronous object that holds the media when loaded.
+     */
+    MediaLoader getMediaAsync(Span s);
+
+    Span append(String s);
+    
+}
+
+interface Media {
+    final int TEXT, IMAGE, AUDIO, VIDEO;
+    int getType();
+    ... ??? Casts?
+}
+
+interface MediaLoader {
+    /** Whether loading is complete.
+     */
+    boolean isReady();
+
+    /** Whether the media has been correctly, fully loaded
+     * without errors.
+     */
+    boolean isValid();
+    ... ???
+
+    /** Stop loading.
+     */
+    void close();
+
+    /** Get the final media.
+     * null = not yet here.
+     */
+    Media getMedia();
+}
+\end{verbatim}
+
+\section{Decentralized unique ID scheme proposal}
+
+Let IDs be octet sequences of arbitrary nonzero length.
+
+An ID is always either \emph{assigned} or \emph{unassigned}.
+
+The ID x is \emph{inferior} to ID y iff y is an initial subsequence of
+x.  An ID is inferior to itself.
+
+Let A be a mediaserver and x be an ID.  Now \emph{A has delegated x}
+is a relation.
+
+Let A be a mediaserver and x be an ID.  Now define that \emph{x
+  available to A} iff it is not inferior to an ID that A has
+delegated.
+
+Define the relation \emph{A has authority over x}, where A is a
+mediaserver and x is an ID.
+
+The following invariants hold:
+\begin{itemize}
+\item For every ID there is a mediaserver that has authority over it.
+\item If a mediaserver has authority over an unassigned ID, it can
+  make it an assigned ID.
+\item If an ID is not available to a mediaserver, the mediaserver does
+  not have authority over it.
+\item If a mediaserver has authority over an ID x, then it has
+  authority over every ID that is both inferior to the ID x and is
+  available to the mediaserver.
+\item If a mediaserver has authority over an unassigned ID and if
+  there are no assigned IDs inferior to that ID, it can delegate
+  the ID.
+\end{itemize}
+
+The idea is that when a mediaserver needs a fresh ID, it takes an ID
+it has authority over.  If it has no such IDs, it requests that some
+other mediaserver delegates authority over some other ID to it.
+
+\subsection{Advantages}
+
+I believe that this scheme guarantees network-wide unique IDs.  It
+also requires no central agency that gives out valid IDs.
+
+\subsection{Vulnerabilities}
+
+If there are two distinct networks and data is shared between the
+networks, havoc occurs.  The solution is to have one conceptual global
+network.  The network can be disconnected; if every connected
+subnetwork is seeded with a distinct part of the ID space, then each
+operates autonomously after seeding.
+
+It is possible for a malicious mediaserver to take authority over lots
+of IDs.  However, this will not have any fatal effects on the
+mediaserver network.
+
+A hostile mediaserver may also distribute invalid ids around that it has
+no authority over. This is probably the most serious attack.
+
+\subsection{Crypto?}
+
+It would be good to involve cryptographic signatures here so that
+assigning and delegating IDs requires a verifiable digital signature
+somehow. Needs work.
+
+\subsubsection{A scheme}
+
+One possible - probably incomplete - scheme follows:
+
+Every mediaserver shall have an asymmetric key pair for cryptographic
+signing.  Additionally, there shall be a key pair for the network
+distinct from the mediaserver keys.  Now, a mediaserver having
+authority over an ID shall possess an authority certificate for that
+ID (or to an ID that ID is inferior to).
+
+When a mediaserver having authority over an ID wants to assign that ID
+to a datum, it generates a data packet containing both the datum and
+the authority certificate it has and signs that packet.
+
+When a mediaserver having authority over an ID wants to delegate that
+ID to another mediaserver, it generates a new certificate as follows:
+it generates a data packet containing the authority certificate of the
+delegator the ID being delegated and information that uniquely
+specifies the delegatee's public key (key ID, key size and fingerprint
+or something like that), and then signs that packet.  This signed
+packet is the new certificate.  The delegatee shall then broadcast the
+certificate to the whole network.
+
+(An attack deflector:) If a mediaserver has a valid authority
+certificate for an ID and it receives a conflicting valid authority
+certificate, then there is a rogue mediaserver that is delegating the
+same ID to several mediaserver.  The identity of the rogue should be
+easy to determine and sanctions (such as removing from the network)
+doable.
+
+A valid certificate is defined recursively: a certificate signed by
+the network key is valid, and a certificate containing a valid
+certificate for the correct ID is valid.
+
+This scheme has at least the vulnerability that a rogue mediaserver
+that is in a good place in a network can prevent the network from
+realizing it's giving out conflicting certificates.
+
+\subsubsection{Another scheme}
+
+\begin{itemize}
+\item There will be two kinds of authority certificates: root
+  certificate and delegation certificate.
+\item Authority certificates are a shared secret between its issuer
+  and its holder.
+\item An authority certificate gives its holder authority over one ID
+  (transitively giving authority over the whole subtree).
+\item The root certificate gives authority over the null ID.  (Change
+  above description to allow it.)
+\item A mediaserver holding an authority certificate for a subtree can
+  generate a new authority certificate for a member of the subtree.
+\item A holder of a certificate must be able to verify that the
+  certificate has an authority path to the root.
+\item It must not be possible to generate an authority certificate 
+\end{itemize}
+
+This scheme has one problem: it does not revoke authority over a
+delegated subtree from the delegator.
+
+\section{Architecture}
+
+The mediaserver proposed architecture has several levels.
+
+\subsection{Physical}
+
+The physical level takes care of retrieving and storing
+spans according to unique global ids. 
+All policy decisions are made on higher levels: this level
+only opens network connections and stores the spans in files
+and removes them according to instructions from the higher level.
+
+No reference counting is done: that is also a problem of the higher
+levels.
+
+\begin{verbatim}
+FOO
+\end{verbatim}
+
+\section{Implementation plan}
+
+\subsection{Phase I}
+
+This is immediate: we need this yesterday.
+
+Unique IDs, at least a preliminary version that will remain unique
+even when better schemes taken into use.
+
+The physical layer, except for:
+Explicit synch by user. No interactive network fetches but
+code to synch up two repositories completely (copy everything
+in both to both).
+No digital signatures or crypto: all systems completely trusted.
+
+
+\subsection{Phase II}
+
+Collections? Overriding? Signatures?
+
+\section{HTTP Interface to Storage}
+
+The storage module will listen on an IP-reachable host on an TCP port
+for incoming connections.  The protocol used will be HTTP/1.0 or
+HTTP/1.1.  It is recommended that the storage module root URL be
+http://localhost/mediaserver/.  The root URL shall be configurable.
+
+The storage module uses the following ID format: first, an arbitrary
+octet sequence is encoded as a sequence of hexadecimal ASCII digits
+(with capital letters); then an ASCII dash is appended; finally, an
+MD5-hash of the octet sequence formed by concatenating the the
+arbitrary octet sequence above and the datum itself is appended as a
+sequence of hexadecimal ASCII digits (with capital letters).
+
+The following requests are supported:
+
+\subsection{Request: GET \emph{root}/data}
+
+A GET request of the base URL with the string \verb+data+ prepended
+will result in a listing of data in the storage module.  Each line
+describes one datum; first comes the ID and then the
+length of the datum in base-10 ASCII representation.  These two fields
+are separated by linear whitespace.
+
+\subsection{Request: GET \emph{root}/data/}
+
+This will result in a human-readable version of the above listing.
+
+\subsection{Request: GET \emph{root}/data/\emph{key}}
+
+A GET request of the base URL with the string \verb+data/+ and the
+datum ID prepended will result in the datum requested.
+
+\subsection{Request: PUT \emph{root}/data/\emph{key}}
+
+Mutatis mutandis.
+
+\subsection{Request: DELETE \emph{root}/data/\emph{key}}
+
+Mutatis mutandis.
+
+\section{Problems}
+
+Word-sized gaps in published documents for deleted words \ra\ guess
+confidential content, or damaging erased content?
+
+\end{document} 
+
+
+

Documentation/Networking/Makefile

@@ -0,0 +1,10 @@
+# DIAGRAMS=linkorder.png beamorder.png
+
+all : ztp.html ztp-ns4.html
+
+ztp.html : ztp.wml
+ztp-ns4.html : ztp.wml
+
+include ../lib.mk
+
+

Documentation/Networking/ZTP-usage.txt

@@ -0,0 +1,70 @@
+Brief usage instructions for the current ZTP implementation
+-----------------------------------------------------------
+
+You need the "ztp" module for both server and client operation.
+
+If your system has a BSD-style syslog service, compile with ARCH=syslog.
+The Makefile is set up to work with Debian-packaged Kaffe, so if you
+use some other JRE, you need to edit Java/arch/syslog/arch.mk.
+
+
+The server
+----------
+
+To start up the server:
+  LD_LIBRARY_PATH=arch/syslog kaffe org.gzigzag.Main -ztpserv 5555 cellscrollfile1
+Here 5555 is the port to bind to.
+
+The only way to stop the server currently is killing it (Ctrl-C or
+SIGTERM signal).
+
+The server does not set up the GZZ-client's system list, so if you
+want to view the space generated by the server, you will have to -new
+it.  The ZTP cells are on the rank along d.ztpserver starting from the
+home cell.  ZTP dimensions and cells have a prefix "ztpserver!".
+
+
+The client
+----------
+
+Create a cell with the content "ZTPclient.PUT".  This will be the
+action to invoke when you want to put data into the server.
+
+Create an association list as follows:
+
+    ---> d.1
+   |         serverFQDN   --- server.example   (server machine FQDN)
+   v            |
+  d.2        serverPort   --- 5555             (server port)
+                |
+             userName     --- adm              (username; currently only adm works)
+                |
+             subspaceName --- ALL              (only ALL currently)
+                |
+             subspace     ----                 (a cell)
+
+Connect the subspace you want to put to the "subspace" cell along
+"d.ztp-subspace".  The subspace is currently defined to be the closure
+of the cell connected to the "subspace" cell along "d.ztp-subspace" in
+positive direction with respect to all available dimensions (from
+d.masterdim) except "d.ztp-subspace" and "d.cellcreation".
+
+Before you can do anything, you need to give your space an ID.  Create
+a cell with the content "SETSPACEID" and another cell with the space
+ID you want as the content.  Have your control cursor on the
+SETSPACEID cell and your data cursor on the space ID cell.  Then
+invoke the action (press ENTER).
+
+Note that the space ID should be unique among all spaces.
+
+To put the subspace to the server, have your control cursor on the
+"STPclient.PUT" action cell mentioned above and your data cursor on
+the first item of the alist ("serverFQDN").  Then invoke the action
+(press ENTER).
+
+To get a subspace from the server, have your control cursor on a cell
+that reads "STPclient.GET" (create one if necessary) and your data
+cursor on the first item of the alist ("serverFQDN").  Then invoke the
+action (press ENTER).
+
+

Documentation/Networking/ZTP.txt

@@ -0,0 +1,161 @@
+ZigZag Transport Protocol
+=========================
+
+Objective: to transfer ZZ subspaces over a network.
+
+This is a datagram-oriented protocol that can operate over both TCP
+and UDP.  The protocol can also operate over a TLS stream.  The
+underlying protocol is assumed to provide for transport-level
+security.
+
+
+Authentication
+--------------
+
+Scenarios
+
+   1. Preauthentication
+      Used with TLS streams.
+
+   2. Plaintext passwords
+
+   3. Cryptographic authentication
+
+What needs to be proven?
+  - identity
+
+For now, we provide only preauthenticated and password-protected
+services.
+
+Authority of the client to order the server to do certain things
+depends on the authenticated client identity.
+
+Privileges:
+   * operator privilege
+   * write privilege
+   * read privilege
+
+
+Naming subspaces
+----------------
+
+Temporary naming:
+
+   -> Client provides server with a definition of a subspace
+   <- Server responds with a name for that subspace
+
+   Client may not assume that the name is valid after this session.
+
+   This exchange may not fail for any reason.
+
+Permanent naming
+
+   -> Client provides a server with a name and a definition of
+      a subspace
+
+   If successful, the name will be valid until deleted, even across
+   sessions.
+
+   Names are arranged into a hierarchy.  Operators of the subspace the
+   name refers to are operators of that name.
+
+   NOTE: This operation requires operator privilege on the parent name.
+
+
+Reading a subspace
+------------------
+
+   -> Client requests a reading of a named subspace
+   <- Server sends a description of the subspace
+
+   NOTE: This operation requires read privileges on that subspace
+
+
+Writing a subspace
+------------------
+
+   -> Client requests a writing of a named subspace
+   <- Server gives client goahead
+   -> Client sends a description of the subspace
+
+   NOTE: This operation requires read privileges on that subspace
+
+
+User administration
+-------------------
+
+Admin stuff:
+* Create a user
+* Grant privileges to user
+* Suspend a user
+* Delete a user
+
+User stuff:
+* Password change
+
+
+PROTOCOL SPECIFICATION
+======================
+
+Messages:
+
+from client:
+   PASSAUTH <username> <password>
+
+   TMPNAME <seqno>
+
+   PERMNAME <name> <seqno>
+      SUBSPACE (see TMPNAME)
+
+   READ <name> <seqno>
+
+   WRITE <name> <seqno>
+
+   NEWUSER <name>
+   DELUSER <name>
+
+   GRANTPRIV <user> <priv> 
+   REVOKEPRIV <user> <priv>
+
+   FREEZEUSER <user>
+   THAWUSER <user>
+
+   CHPASS <user> <pass>
+
+   QUIT
+
+sequences:
+      SEQ <seqno> <num> CELL <cellid>
+      SEQ <seqno> <num> HARDDIM <dimid>
+      SEQ <seqno> <num> SOFTDIM <dimid>
+      SEQ <seqno> <num> CONTENT <cellid> <content>
+      SEQ <seqno> <num> CONNECT <dimid> <cellid> <cellid>
+      SEQ <seqno> <num> END
+
+UDP SEQ responses:
+      REQ SEQ <seqno> <num>
+      ACK SEQ END
+      SEQ FINISH
+      ACK SEQ FINISH
+
+non-SEQ responses:
+   OK
+   ERR <err code>
+
+Operation over TCP or TLS:
+   - all messages are sent ONCE
+   - SEQ messages lack seqno and num, SEQ requests lack seqno
+   - no acknowledgement
+   - each non-SEQ message is responded with OK or ERR
+   - OK and ERR are not responded to
+
+Operation over UDP:
+   - all non-SEQ messages are resent periodically until acknowledged
+     with OK or ERR
+   - OK and ERR are not acknowledged
+   - SEQ END is resent periodically until acknowledged with ACK SEQ END
+   - after SEQ END, SEQ receiver may send REQ SEQ requests periodically
+     until it receives a corresponding SEQ message, sent once.
+   - after ACK SEQ END and any REQ SEQ, the SEQ session is ended by SEQ FINISH
+     sent by receiving side until it receives ACK SEQ FINISH message
+

Documentation/Networking/mock-ZTPTCP.txt

@@ -0,0 +1,74 @@
+Generic command syntax:
+
+   command = ASCII word, args, crlf;
+   ASCII word = ASCII letter, ASCII word;
+   letter = 65 | 66 | 67 | 68 | 69 | 70 | 71 | 72 | 73
+          | 74 | 75 | 76 | 77 | 78 | 79 | 80 | 81 | 82 | 83
+          | 84 | 85 | 86 | 87 | 88 | 89 | 90 | 97 | 98 | 99
+          | 100 | 101 | 102 | 103 | 104 | 105 | 106 | 107
+          | 108 | 109 | 110 | 111 | 112 | 113 | 114 | 115
+          | 116 | 117 | 118 | 119 | 120 | 121 | 122;
+   whitespace = | 9 | 32;
+   crlf = 13, 10;
+   args = | whitespace, arg, args;
+   arg = ASCII word | ASCII number | UNICODE string;
+   ASCII number = 48 | 49 | 50 | 51 | 52 | 53 | 54 | 55 | 56 | 57;
+   UNICODE string = 34, UNICODE string without quotes, 34;
+   UNICODE string without quotes = | quoted UNICODE char | UNICODE string without quotes;
+   quoted UNICODE char = UNICODE char (not 34) | 34, 34;
+
+Response code theory:
+
+  X.Y.Z:
+     X denotes success / failure:
+        1: Positive Preliminary response
+        2: Positive Completion response
+        3: Positive Intermediate response
+        4: Transient Negative Completion response
+        5: Permanent Negative Completion response
+
+     Y denotes response class:
+        0: Syntax
+        1: Information
+        2: Connections
+        3: Authentication
+        4: Subspaces
+
+     Z with X and Y specifies exact problem
+
+Initial greeting:
+  2.2.0 Hello there!
+
+Generic responses:
+  5.0.1 What?  (Syntax error)
+  4.2.1 Service unavailable, closing transmission channel
+
+
+QUIT
+
+Responses:
+  2.2.1 Bye
+
+AUTH/PRE & AUTH/PASS
+
+Responses
+  5.3.0 Access denied
+  5.3.1 User disabled
+  2.3.0 OK
+
+PUT
+  2.4.0 Subspace successfully put
+  3.4.0 Pleace proceed with subspace data
+  5.4.0 Aborted PUT
+  5.4.1 No such subspace
+  5.4.2 Cannot put cells lacking a space ID
+
+GET
+  2.4.1 Subspace successfully got
+  3.4.1 Proceeding with subspace data
+  5.4.1 No such subspace
+
+Subspace data:
+   C <cellid> <data>   -- content
+   R <dimid> <cellid> <cellid> ... <cellid>  -- rank
+   F -- finish

Documentation/Networking/ztp.wml

@@ -0,0 +1,855 @@
+#########
+## TODO
+#    * scrolls
+#    * 
+#########
+
+
+#use wml::std::grid
+
+<define-tag keyword endtag=required><strong>%body</strong></define-tag>
+<define-tag mvar endtag=required><em>%body</em></define-tag>
+
+
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+   "http://www.w3.org/TR/html4/strict.dtd"> 
+<!--
+	NOTE! This file uses WML 2.0.1
+
+	PLEASE PLEASE PLEASE don't edit .HTML. Edit .WML!!!! Actually,
+	it's more important for you since your changes will be LOST FOREVER
+	if you edit the .HTML files.
+ -->
+
+<html>
+ <head>
+  <title>GZigZag networking: ZigZag Transfer Protocol</title>
+
+#include '../wmlinc/catart.wml'
+
+<H1>GZigZag networking: ZigZag Transfer Protocol</H1>
+<pre>$Id: ztp.wml,v 1.3 2001/02/06 12:12:17 ajk Exp $</pre>
+
+Written by <br>
+<b>Antti-Juhani Kaijanaho</b> <br>
+(add your name here if you do any significant modification)
+
+<p>
+{#MYTOC#}
+
+<s1>On naming</s1>
+
+<p>The name of this protocol is the ZigZag Transfer Protocol, or ZTP,
+as suggested by Tuomas Lukka.  Early versions of this protocol were
+called the Subspace Transfer Protocol, or STP, which we did not like.
+
+<p>Note that the acronym ZTP stands also for Zangelding Transfer
+Protocol.  Due to the different usages for the two protocols, we don't
+expect that serious confusion will result from this.
+
+<s1>On subspaces</s1>
+
+<p>A subspace S' of a ZigZag space S is a ZigZag space with the
+following properties:
+
+<ol>
+<li>The set of cells in S' is a subset of the set of cells in S
+<li>The set of connections in S' is a subset of the set of connection in S
+</ol>
+
+<p>A subspace selector is a function mapping ZigZag spaces into their
+subspaces.  A subspace selector can be described by the triplet
+&lt;C,&nbsp;H,&nbsp;S&gt;, where
+
+<dl>
+
+<DT>C</DT>
+<dd>is a set of cells,</dd>
+
+<dt>H</dt>
+<dd>is a set of dimensions, and</dd>
+
+<dt>S</dt>
+<dd>is a set of dimensions</dd>
+
+</dl>
+
+<p>and where H and S are disjoint.
+
+<p>Given a ZigZag space Z, a subspace selector chooses a subspace as
+follows: the set of cells is constructed as the set of cells reachable
+from the cells in C through connections along dimensions in H; and the
+set of connections is constructed as the set of those connections from
+Z whose both ends are in the subspace and whose dimension is in H or S.
+
+<S1>User access privilege management</s1>
+
+<p>Once the user is authenticated, her actions are limited by her
+access privileges.  There are four types of privileges:
+
+<ul>
+<li>space administrator privileges (SAP)
+<li>subspace operator privileges (SOP)
+<li>subspace write privileges (SWP)
+<li>subspace read privileges (SRP)
+</ul>
+
+<p>
+All but SAP are associated with a subspace.  The subspace privileges
+apply to the subspace itself and any subspaces of that subspace.
+
+<p> If a user has SOP, SWP or SRP in a subspace S and the same
+privileges in a subspace T of S, and the privileges to T are revoked,
+the privilege to S is unaffected by the revocation.
+
+<s2>Space Administrator Privileges (SAP)</s2>
+
+<p>A user having SAP is authorized to create, delete, suspend and
+resume users, and give and revoke users their SOP to any subspace, and
+give and revoke users their SAP.  A user having SAP is also authorized
+to revoke any user's SOP, SWP or SRP to any subspace.
+
+<s2>Subspace Operator Privileges (SOP)</s2>
+
+<p>A user having SOP on a subspace S is authorized to give or revoke
+any user their SOP, SWP or SRP to any subspace of S, including S
+itself.
+
+<s2>Subspace Write Privileges (SWP)</s2>
+
+<p>A user having SWP on a subspace S is authorized to initiate
+transfer of any subspace of S, inclusing S itself, from the client to
+the server.
+
+<s2>Subspace Read Privileges (SRP)</s2>
+
+<p>A user having SRP on a subspace S is authorized to initiate
+transfer of any subspace of S, including S itself, from the server to
+the client.
+
+<s1>Protocol overview</s1>
+
+<p>
+ZTP is actually two similar protocols for the same purpose.  One
+operates over a reliable stream; we call this ZTP/TCP.  The other
+operates over a datagram service; we call this ZTP/UDP.  Note that
+other underlying protocols than TCP or UDP are possible; the names are
+chosen for their mnemonic value, not for their accuracy.
+
+<p>
+The datagram service used by ZTP/UDP is assumed to fail only in that
+sent datagrams may be lost en route and that datagrams may arrive out
+of order, and datagrams may be duplicated.  In particular, it is
+assumed that any arriving datagrams are uncorrupted.
+
+<p>
+All transfer protocols used by ZTP/TCP and ZTP/UDP are assumed to
+provide for confidentiality and integrity.  However, the transfer
+protocols are not necessarily assumed to provide for authentication.
+
+<p>Thus, good transfer protocols to use with ZTP/TCP are
+<ul>
+<li>TLS over TCP over IP
+<li>SSL over TCP over IP
+<li>TCP over IPSec
+<li>SSH protocol
+</ul>
+
+<p>UDP over IPSec is a good protocol to use with ZTP/UDP.
+
+<p>In a trusted environment, also TCP over IP with ZTP/TCP and UDP
+over IP in ZTP/TCP can be used.  Hovewer, <strong>using ZTP/TCP over
+TCP over plain IP and using ZTP/UDP over UDP over plain IP on the
+global Internet is DANGEROUS</strong>.
+
+<p>The ZTP protocol consists of several modules.  The modules are:
+<ul>
+<li>authentication
+<li>user administration
+<li>subspace administration
+<li>subspace naming
+<li>subspace transfer
+<li>SEQ scheme
+</ul>
+
+<p>The authentication module actually consists of several alternative
+modules.  <dfn>Pre-authentication</dfn> is used when ZTP operates over
+authenticating underlying protocols.  It is also useful for
+anonymous-access-only read-only servers, where there is no need for
+real authentication. <dfn>Password authentication</dfn> is used when
+the underlying protocol provides for data integrity and
+confidentiality but not authentication, and in trusted unencrypted
+environments.  <dfn>Cryptographic authentication</dfn> will use
+cryptographic means to authenticate the user and is meant to be used
+in hostile environments.  This specification will not define any
+cryptographic authentication methods.
+
+<p>User administration module handles such things as adding, deleting,
+suspending and resuming users.  It is all things that require SAP.
+
+<p>Subspace administration module allows a user having SOP to a
+subspace S give and revoke SOP, SWP and SRP to any subspace of S,
+including S itself.
+
+<p>Subspace naming module uses the SEQ scheme to define a subspace and
+then gives a name for it.  All other subspace operations use that
+name.
+
+<p>Subspace tranfer module uses the SEQ scheme to transfer a subspace
+from the client to the server (which requires SWP) and from the server
+to the client (which requires SRP).
+
+<p>The SEQ scheme is a method for dumping a subspace content from the
+sender (either the client or the server) to the receiver (either the
+client or the server, the one which is not the sender).  The scheme is
+simple in ZTP/TCP.  In ZTP/UDP, the scheme is optimized for
+transmission paths with low packet loss, allowing for information to
+be used as the packets arrive, even if they come out of order.
+
+<s2>Protocol walkthrough</s2>
+
+<p>An ZTP protocol instance starts by establishing a session.  In
+ZTP/TCP, this is handled by the underlying protocol, so in ZTP/TCP
+this phase consists of no messages.  In ZTP/UDP, a session is
+identified by an octet negotiated by the parties in a handshake
+roundtrip.  
+
+<p>After session has been established, user authentication is
+performed.  This is initiated by the client who sends a request for
+authentication specifying which authentication method is desired.  The
+rest of the exchange depends on the authentication method; the
+authentication phase is ended by an okaying or rejecting message from
+the server.
+
+<p>After successful authentication, the client in the session is
+assumed to be controlled by the authenticated user.  It can then
+initiate any process for which the user has sufficient privileges.
+
+<p>XXX Use cases
+
+<p>Connection can be closed at any time.  It is preferred that the
+connection closure scheme is used.  The closure can be initiated by
+either party at any time.  In case connection is not properly closed,
+a connection shall have a timeout of at least ten minutes for forcibly
+closing the connection if no messages are exchanged in that time.
+
+<s1>Authentication schemes</s1>
+
+There are three schmes for authentication in ZTP.  Preauthentication
+presupposes that the underlying protocol provides authentication in
+some implementation-defined manner.  Password authentication uses a
+trivial shared secret protocol to establish the authenticity of the
+user.  A slot for future amendment of the protocol is reserved; it is
+expected that cryptographic authentication will be preferred over
+password authentication in the future.  This protocol specification
+does not define any cryptographic authentication methods.
+
+<s2>Preauthentication</s2>
+
+<p>In preauthentication, the underlying protocol provides for enough
+information to determine the authencity of the user at the client end.
+The mechanism for that is beyond the scope of this specification.
+
+<p>The client requesting preauthentication shall send an AUTH REQ/PRE
+message containing the user name for which authentication is desired.
+If the server determines that the client is sufficiently authenticated
+by the underlying protocol to be that user name, and the named user
+exists and is not suspended, it shall respond with the AUTH OK
+message.  Otherwise it shall respond with an AUTH ERR message and
+initiate connection closure.
+
+<s2>Password authentication</s2>
+
+<p>In password authentication the client provides the server with a
+user name / password pair, which the server compares with its own
+records.  If the pair matches, the user is successfully authenticated.
+The password is a shared secret; however, the server may use one-way
+functions to store the information it needs of the password.
+
+<p>The client requesting password authentication shall send an AUTH
+REQ/PASS message containing the user name for which authentication is
+desired and the related password.  If the password is determined to be
+the same as the password for the user name stored in the server's
+records, and the user is not suspended, the server shall respond with
+the AUTH OK message.  If there is no such user name, or the password
+does not match, or the user is suspended, the server MUST respond with
+an AUTH ERR message and initiate connection closure.
+
+<s2>AUTH message details</s2>
+
+<s3 authreqresponses>Responses to AUTH REQ messages</s3>
+
+<p>The server MUST respond to an <keyword>AUTH REQ</keyword> message
+with either the message <keyword>AUTH OK</keyword> or the message
+<keyword>AUTH ERR</keyword>, based on the following rules:
+
+<ul>
+
+<li>If the server does not support the requested authentication type
+at all, it MUST respond with <keyword>AUTH ERR</keyword>.
+
+<li>If the <mvar>username</mvar> is the name of an nonexistent user,
+or it is an existing user who is not properly authenticated, the
+server MUST respond with <keyword>AUTH ERR</keyword>.  The message
+sent MUST be identical between the different reasons in this item for
+issuing the message.  In other words, it MUST NOT be possible for the
+client to determine based on the form of the message whether the user
+name exists or not.  An example of a proper explanation text for the
+message is "Access denied".
+
+<li>If the <mvar>username</mvar> is properly authenticated and the
+named user is disabled, the server MUST respond with <keyword>AUTH
+ERR</keyword>.  An example of a proper explanation text for the
+message is "User disabled".  Note that this kind of a message MUST NOT
+be sent if the user is not properly authenticated.
+
+<li>If the <mvar>username</mvar> exists and is properly authenticated
+and it is not disabled, the server SHOULD respond with <keyword>AUTH
+OK</keyword>.  However, the server MAY also respond with <keyword>AUTH
+ERR</keyword> (for example, if there are local limits on the number of
+simultaneous users and the limit is exceeded), in which case the
+explanation text for the message SHOULD make it clear why the
+authentication was rejected.
+
+</ul>
+
+
+<s3>AUTH REQ/PRE</s3>
+
+<s4>Synopsis</s4>
+
+<p>
+<keyword>AUTH REQ/PRE</keyword> <mvar>username</mvar>
+</p>
+
+<ul>
+<li><mvar>username</mvar> : <keyword>string</keyword>
+</ul>
+
+<s4>Description</s4>
+
+<p>This message MUST be sent immediately after the connection has been
+established by a client wishing for preauthentication.  The
+<mvar>username</mvar> is the name of the user for which the
+authentication is requested.
+
+<p>The server responses to this message are defined in <ref
+authreqresponses>
+
+<s3>AUTH REQ/PASS</s3>
+
+<s4>Synopsis</s4>
+
+<p><keyword>AUTH REQ/PASS</keyword> <mvar>username</mvar> <mvar>password</mvar></p>
+
+<ul>
+<li><mvar>username</mvar>, <mvar>password</mvar> : <keyword>string</keyword>
+</ul>
+
+<s4>Description</s4>
+
+<p>This message MUST be sent immediately after the connection has been
+established by a client wishing for password authentication.  The
+<mvar>username</mvar> is the name of the user for which the
+authentication is requested.
+
+<p>The server verifies the authenticity of the user by verifying that
+the <mvar>password</mvar> is the same as the valid password for the
+<mvar>username</mvar> according to the server's records.  Note that
+the server MAY store only the result of a one-way hashing of the
+password instead of the password itself, if this information can be
+used to reliably ascertain the validity of a given
+<mvar>password</mvar>.
+
+<p>The server responses to this message are defined in <ref
+authreqresponses>
+
+<s3>AUTH OK</s3>
+
+<s4>Synopsis</s4>
+
+<p><keyword>AUTH OK</keyword></p>
+
+<s4>Description</s4>
+
+<p>This message indicates that the server has accepted the
+authenticity of the client as the username given in the earlier
+<keyword>AUTH REQ</keyword> message.  This message concludes the
+authentication phase.
+
+<s3>AUTH ERR</s3>
+
+<s4>Synopsis</s4>
+
+<p><keyword>AUTH ERR</keyword> <mvar>explanation</mvar></p>
+
+<ul>
+
+<li><mvar>explanation</mvar> : <keyword>string</keyword>
+
+</ul>
+
+<s4>Description</s4>
+
+<p>This message indicates that the server has not accepted the
+authenticity of the client as the username given in the earlier
+<keyword>AUTH REQ</keyword> message.  The server, after sending this
+message, SHOULD immediately initiate connection closure.
+
+<p>The <mvar>explanation</mvar> SHOULD be a human-readable description
+of the reason for the authenticity rejection.  Note that the server
+SHOULD word the explanation so that the client cannot determine
+whether it was failed authentication or a nonexistent username that
+prompted the <keyword>AUTH ERR</keyword> message.
+
+<s1>User administration</s1>
+
+<p>The purpose of the user administration module in ZTP is to allow the
+administrator to administrate users remotely without needing to resort
+to implementation-defined behaviour.
+
+<p>Users have the following characteristics tunable using ZTP:
+
+<ul>
+<li>User name (<mvar>UNAME</mvar> : <keyword>string</keyword>)
+<li>Permission to be preauthenticated (<mvar>AUTH/PRE</mvar> : <keyword>boolean</keyword>)
+<li>Permission to be password-authenticated (<mvar>AUTH/PASS</mvar> : <keyword>boolean</keyword>)
+<li>Is suspended or not (<mvar>SUSP</mvar> : <keyword>boolean</keyword>)
+<li>Permission to change password (<mvar>CHPASS</mvar>: <keyword>boolean</keyword>)
+<li>Password (<mvar>PASS</mvar> : <keyword>string</keyword>)
+<li>Has SAP or doesn't have SAP (<mvar>SAP</mvar> : <keyword>boolean</keyword>)
+</ul>
+
+<p>The user administration module consists of one scheme for editing
+and one scheme for viewing all these user data.  The edition scheme
+can be also used for adding and deleting new users.
+
+<p>A user can view their own data regardless of permissions.  The user
+can change the password if their <mvar>CHPASS</mvar> flag is set to
+true.
+
+<s2>The server side user management concept</s2>
+
+<p>This section defines a conceptual model for the server side user
+management for ZTP.  Server implementations MAY use other
+implementation strategies so long as the effects observable by the
+clients are the same as with this model.
+
+<p>In the server, there is a table of users.  The table consists of
+records containing the following information:
+
+<ul>
+<li><mvar>username</mvar> : <keyword>string</keyword>
+<li><mvar>password</mvar> : <keyword>string</keyword>
+<li><mvar>status</mvar> : <keyword>userstatus</keyword>
+</ul>
+
+<p>A particular record may be written as a triplet
+&lt;<mvar>username</mvar>, <mvar>password</mvar>,
+<mvar>status</mvar>&gt;.
+
+<p>The third element, <mvar>status</mvar> is an octet-length bit
+vector with the following structure:
+
+<grid layout="8x2" width="100%" border="1">
+<cell>Bit 7</cell>
+<cell>Bit 6</cell>
+<cell>Bit 5</cell>
+<cell>Bit 4</cell>
+<cell>Bit 3</cell>
+<cell>Bit 2</cell>
+<cell>Bit 1</cell>
+<cell>Bit 0</cell>
+
+<cell>Reserved</cell>
+<cell>Reserved</cell>
+<cell>Reserved</cell>
+<cell>AUTH/PASS</cell>
+<cell>AUTH/PRE</cell>
+<cell>SAP</cell>
+<cell>CHPASS</cell>
+<cell>SUSP</cell>
+</grid>
+
+<p>This data type is referred to in type definitions as
+<keyword>userstatus</keyword>.  Note that the elements marked as
+Reserved MUST have the value <keyword>false</keyword>.
+
+<p>The table of users is indexed by user names.  There may be at most
+one record with a given <mvar>username</mvar> in the table.
+
+<p>In the table, the following operations are allowed:
+
+<ul>
+
+<li>insertion of a new user record;
+
+<li>replacement of a user record;
+
+<li>deletion of a user record; and
+
+<li>accessing a complete user record.
+
+</ul>
+
+<p>All of them are atomic.  This means that, for the forementioned
+operations, the following are true:
+
+<ul>
+
+<li>If an operation fails, the table will remain in the state it was
+before the attempt.
+
+<li>Operations never overlap; thus at most one operation is in
+progress at any time.
+
+</ul>
+
+<p>A user exists, if and only if there is a record with that username
+on the table.  A user is disabled if and only if there is a record
+with that username on the table and the <mvar>SUSP</mvar> element of
+the <mvar>status</mvar> element of that record has the value
+<keyword>true</keyword>.  A user has SAP if and only if there is a
+record with that username on the table and the <mvar>SAP</mvar>
+element of the <mvar>status</mvar> element of that record has the
+value <keyword>true</keyword>
+
+<s2>UADM message details</s2>
+
+<s3>UADM NEW</s3>
+
+<s4>Synopsis</s4>
+
+<p><keyword>UADM NEW</keyword> <mvar>stat</mvar> <mvar>uname</mvar> <mvar>passwd</mvar>
+</p>
+
+<ul>
+<li><mvar>stat</mvar> : <keyword>userstatus</keyword>
+<li><mvar>uname</mvar>, <mvar>passwd</mvar> : <keyword>string</keyword>
+</ul>
+
+<s4>Description</s4>
+
+<p>This message is sent by the client when it wants to create a new
+user.</p>
+
+<p>After receiving this message, the server MUST follow the following
+step-by-step algorithm (the term "client user" refers to the user
+authenticated to control the session where the message was sent):
+
+<ul>
+
+<li>Check whether the client user has SAP.  If not, the server MUST
+send in response the <keyword>UADM E/NOPERM</keyword> message, and end
+the processing of the message here.
+
+<li>Check whether the user <mvar>uname</mvar> exists.  If it does, the
+server MUST send in response the <keyword>UADM E/EXISTS</keyword>
+message and end the processing of the message here.
+
+<li>The server SHOULD check that it has enough resources to handle
+this new user (the criteria are implementation-defined and MAY include
+local considerations).  If it determines that it doesn't have the
+resources, the server MUST send in response the <keyword>UADM
+E/NORES</keyword> message and end the processing of the message here.
+
+<li>The server MUST insert the record &lt;<mvar>uname</mvar>,
+<mvar>passwd</mvar>, <mvar>stat</mvar>&gt; into the user table.  If
+this fails, it MUST respond with the message <keyword>UADM
+E/PROB</keyword>, otherwise it MUST respond with the message
+<keyword>UADM OK</keyword>.
+
+</ul>
+
+
+<s1>Payload transfer: the SEQ scheme</s1>
+
+<p>
+The actual payload of the protocol, the subspace data, is transferred
+over by the SEQ scheme.
+
+<p>The SEQ scheme consists of five SEQ data messages and four SEQ
+control messages.  The data messages are
+
+<dl>
+
+<dt>SEQ CELL</dt>
+<dd>Specifies a root cell for a subspace</dd>
+
+<dt>SEQ HARDDIM</dt>
+<dd>Specifies a hard dimension for a subspace</dd>
+
+<dt>SEQ SOFTDIM</dt>
+<dd>Specifies a soft dimension for a subspace</dd>
+
+<dt>SEQ CONTENT</dt>
+<dd>Transfers over the content of a subspace</dd>
+
+<dt>SEQ RANK</dt>
+<dd>Specifies a subrank in the subspace</dd>
+
+</dl>
+
+<p>
+The SEQ control messages are listed below.
+
+<dl>
+
+<dt>SEQ FIN</dt>
+<dd>Initiates finalization phase of the SEQ scheme</dd>
+
+<dt>SEQ REQ</dt>
+<dd>Requests that a SEQ data message is resent</dd>
+
+<dt>SEQ ERR</dt>
+<dd>Response for a broken SEQ REQ.</dd>
+
+<dt>SEQ END</dt>
+<dd>Ends the SEQ scheme instance</dd>
+
+</dl>
+
+<p>A SEQ scheme instance has a sending end and a receiving end.  When
+the server is the sending end, the client is the receiving end and
+vice versa.
+
+<p>In ZTP/TCP, the SEQ scheme consists of a number of SEQ data
+messages and is finished by a SEQ END message.
+
+<p>In ZTP/UDP, the SEQ scheme consists of two phases: the data
+transfer phase and the finalization phase.  The data transfer phase
+consists of a number of SEQ data messages and is ended by a SEQ FIN
+message which also starts the finalization phase.  Then the receiver
+end of the SEQ scheme sends one or more SEQ REQ messages and the
+sender end responds with an appropriate SEQ data message.  The
+finalization phase is ended by a SEQ END by both parties.
+
+<s2>SEQ message details</s2>
+
+<s3>SEQ/DATA message template</s3>
+
+<s3>SEQ/CTL message template</s3>
+
+<s3>SEQ CELL</s3>
+
+<s4>Synopsis</s4>
+
+<p>
+<keyword>SEQ/DATA</keyword> <keyword>CELL</keyword> <mvar>cellid</mvar><br>
+<ul>
+<li><mvar>cellid</mvar> : <keyword>string</keyword>
+</ul>
+
+<s4>Description</s4>
+
+<p>This message defines that the cell <mvar>cellid</mvar> is a root
+cell for the subspace being described.
+
+<s3>SEQ HARDDIM</s3>
+
+<s4>Synopsis</s4>
+
+<p>
+<keyword>SEQ/DATA</keyword> <keyword>HARDDIM</keyword> <mvar>dimid</mvar>
+</p>
+
+<ul>
+<li><mvar>dimid</mvar>: <keyword>string</keyword>
+</ul>
+
+<s4>Description</s4>
+
+<p> This message defines that the dimension <mvar>dimid</mvar> is one
+of the defining dimensions for the subspace being described.  In other
+words, this defines that any cell connected to any cell in the
+subspace along dimension <mvar>dimid</mvar> also is in the subspace.
+
+<p>If in a SEQ scheme instance a dimension is specified using
+<keyword>SEQ HARDDIM</keyword>, it SHOULD NOT be specified in the same
+SEQ scheme instance using <keyword>SEQ SOFTDIM</keyword>.
+
+<s3>SEQ SOFTDIM</s3>
+
+<s4>Synopsis</s4>
+
+<p>
+<keyword>SEQ/DATA</keyword> <keyword>SOFTDIM</keyword> <mvar>dimid</mvar>
+</p>
+<ul>
+<li><mvar>dimid</mvar>: <keyword>string</keyword>
+</ul>
+
+<s4>Description</s4>
+
+<p>This message defines that any connections along dimension
+<mvar>dimid</mvar> between cells that are in the subspace are included
+in the subspace.  However, this dimension will not take part in the
+definition of the cell set of the subspace.
+
+<p>If in a SEQ scheme instance a dimension is specified using
+<keyword>SEQ SOFTDIM</keyword>, it SHOULD NOT be specified in the same
+SEQ scheme instance using <keyword>SEQ HARDDIM</keyword>.
+
+<s3>SEQ CONTENT</s3>
+
+<s4>Synopsis</s4>
+
+<p> <keyword>SEQ/DATA</keyword> <keyword>CONTENT</keyword>
+<mvar>content-type</mvar> <mvar>cellid</mvar> <mvar>content</mvar>
+</p>
+<ul>
+<li><mvar>content-type</mvar>: <keyword>octet</keyword>
+<li><mvar>cellid</mvar>: <keyword>string</keyword>
+<li><mvar>content</mvar>: <keyword>octet</keyword>[]
+</ul>
+
+<s4>Description</s4>
+
+<p>This command transfers the content of a cell, which this protocol
+treats as an octet stream with no underlying structure.  The type of
+the content is indicated in this messages; the following content types
+are now established:
+
+
+<grid layout="2x3" width="100%">
+
+<cell>0</cell>
+<cell>Octet stream, ie. unknown format</cell>
+
+<cell>1</cell>
+<cell>Unicode text in UTF-8 encoding</cell>
+
+<cell>2</cell>
+<cell>A span</cell>
+
+</grid>
+
+<s3>SEQ RANK</s3>
+
+<s4>Synopsis</s4>
+
+<p><keyword>SEQ/DATA</keyword> <keyword>RANK</keyword>
+<mvar>dimid</mvar> <mvar>cellarray</mvar>
+
+<ul>
+<li><mvar>dimid</mvar> : <keyword>string</keyword>
+<li><mvar>cellarray</mvar> : <keyword>string</keyword>[]
+</ul>
+
+<s4>Description</s4>
+
+<p>This message denotes a subrank along dimension <mvar>dimid</mvar>.
+
+<p>The precise definition of this is as follows:
+<mvar>cellarray</mvar>[<mvar>n</mvar>] is connected posward to
+<mvar>cellarray</mvar>[<mvar>n</mvar>+1] for all <mvar>n</mvar>
+between zero, inclusive, and the length of <mvar>cellarray</mvar>
+minus one, exclusive.  More than one <keyword>SEQ RANK</keyword>
+message MAY define the same connection.  Two <keyword>SEQ
+RANK</keyword> messages MUST NOT define two conflicting connections
+(that is, a connection posward or negward from the same cell to two
+different cells).
+
+<s3>SEQ FIN</s3>
+
+<s4>Synopsis</s4>
+
+<p><keyword>SEQ/CTL</keyword> <keyword>FIN</keyword> <mvar>dmcount</mvar>
+
+<ul>
+<li><mvar>dmcount</mvar>: <keyword>uint32</keyword>
+</ul>
+
+<s4>Description</s4>
+
+<p>This message closes the data transfer phase of a SEQ scheme
+instance and opens its finalization phase.
+
+<p>The parameter <mvar>dmcount</mvar> MUST specify the number of
+unique SEQ data messages sent during the data transfer phase of the
+SEQ scheme instance.
+
+<p>In ZTP/UDP, the sending end of the SEQ scheme instance MUST send
+this message repeatedly after sending the last SEQ data message in the
+data transfer phase, until it receives either a SEQ REQ or a SEQ END
+message.
+
+<p>When the receiving end of the SEQ scheme instance first receives
+this message, it SHOULD check which data messages it did receive and
+issue SEQ REQ messages for each missing message.  When it has received
+all data messages, it MUST send a SEQ END message.  It should ignore
+all further SEQ FIN messages associated with that SEQ scheme instance.
+
+<p>This message MUST NOT be sent in ZTP/TCP.
+
+<s3>SEQ REQ</s3>
+
+<s4>Synopsis</s4>
+
+<p>
+<keyword>SEQ/CTL</keyword> <keyword>REQ</keyword> <mvar>seq</mvar>
+</p>
+
+<ul>
+<li><mvar>seq</mvar> : <keyword>uint32</keyword>
+</ul>
+
+<s4>Description</s4>
+
+<p>This message is sent by the receiving end of the SEQ scheme
+instance to request that the sending end resend the SEQ data message
+with the SEQ message identity number <mvar>seq</mvar>.
+
+<p>The receiving end MUST repeatedly resend this message if it is
+sending it at all, until it receives the data message it's asking for
+or a corresponding <keyword>SEQ ERR</keyword>.
+
+<p>The sending end MUST respond to each <keyword>SEQ REQ</keyword>
+message it receives (even duplicates) by resending the message being
+requested, or with a <keyword>SEQ ERR</keyword> message.
+
+<p>This message MUST NOT be sent in ZTP/TCP
+
+<s3>SEQ ERR</s3>
+
+<s4>Synopsis</s4>
+
+<p>
+<keyword>SEQ/CTL</keyword> <keyword>ERR</keyword> <mvar>seq</mvar>
+</p>
+
+<ul>
+<li><mvar>seq</mvar> : <keyword>uint32</keyword>
+</ul>
+
+<s4>Description</s4>
+
+<p>This message is a response to an invalid <keyword>SEQ REQ</keyword>
+message.  It is to be sent in response to every received invalid
+<keyword>SEQ REQ</keyword> message, even to duplicates.
+
+<p>This message MUST NOT be sent in ZTP/TCP.
+
+<s3>SEQ END</s3>
+
+<s4>Synopsis</s4>
+
+<p>
+<keyword>SEQ/CTL</keyword> <keyword>END</keyword>
+</p>
+
+<s4>Description</s4>
+
+<p>This message ends the SEQ scheme instance.
+
+<p>In ZTP/UDP, the receiving end MUST send this message repeatedly
+after receiving <keyword>SEQ FIN</keyword> and receiving all the data
+it needs, until it receives a <keyword>SEQ END</keyword> message.  The
+sending end MUST respond to every <keyword>SEQ END</keyword> message,
+even duplicates, with a <keyword>SEQ END</keyword> message.
+
+<p>In ZTP/TCP, the sending end MUST send a single <keyword>SEQ
+END</keyword> message after sending all the SEQ data messages it's
+going to send.  The receiving end MUST NOT respond to the <keyword>SEQ
+END</keyword> message.
+

Documentation/Nile/Makefile

@@ -0,0 +1,14 @@
+# DIAGRAMS=linkorder.png beamorder.png
+
+all : nileug.html nileug-ns4.html nile.html nile-ns4.html
+
+niledep = nile.wml ../wmlinc/art.css ../wmlinc/catart.wml  ../wmlinc/common.wml $(DIAGRAMS)
+nileugdep = nileug.wml ../wmlinc/art.css ../wmlinc/catart.wml  ../wmlinc/common.wml $(DIAGRAMS)
+nile.html: $(niledep)
+nile-ns4.html: $(niledep)
+nileug.html: $(nileugdep)
+nileug-ns4.html: $(nileugdep)
+
+include ../lib.mk
+
+

Documentation/Nile/nile.wml

@@ -0,0 +1,259 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
+<!--
+	NOTE! This file uses WML 2.0.1
+
+
+	PLEASE PLEASE PLEASE don't edit .HTML. Edit .WML!!!! Actually,
+	it's more important for you since your changes will be LOST FOREVER
+	if you edit the .HTML files.
+ -->
+
+#include "catart.wml"
+
+<body>
+<DOCTITLE>The nile (nile is a literate editor) applitude</DOCTITLE>
+<pre>$Id: nile.wml,v 1.4 2000/12/08 23:05:20 tjl Exp $</pre>
+<grid layout=3x3 spacing=20>
+ <cell> <b>Tuomas J. Lukka</b> <br>
+ 	<code>lukka@iki.fi</code>
+ </cell>
+</grid>
+
+<substdims>
+
+<p>
+This is a short, living (hopefully) description of the Nile applitude
+and issues related to it.
+
+<p>
+{#MYTOC#}
+
+<s1>Note</s1>
+
+	<p>
+	Writing this document is bothersome, because now that the idea
+	of Nile exists in my head, using conventional writing tools is
+	annoying, to put it mildly. I can now very easily sympathize
+	with the Xanadu group not publishing too much about their work -
+	describing a much easier system for writing using a much more
+	difficult system seems almost a sacrilege.
+
+	<p>
+	However, this must be done. If there is no conversation 
+	and no exchange of ideas, there is nothing.
+
+<s1>Introduction</s1>
+
+	<p>
+	The idea of nile is to experiment with doing "word processing"
+	(for want of better term) in ZigZag.  It is by no means a final
+	system but already the plans for it contain several features
+	not found in current products.
+
+	<p>
+
+<s1>Units</s1>
+
+	<p>
+	Here, we define Nile's units for the following sections.
+	For each unit, the unit itself and the <dfn>insertion points</dfn>
+	are described. The insertion points are simply the points
+	in the stream where units of this type may be inserted.
+
+	<p>
+	XXX Should discuss also cutting and pasting behaviour here.
+
+    <s2>Characters</s2>
+
+    	<p>
+	Not much to say - pretty usual stuff.
+	Characters may be inserted anywhere.
+
+    <s2>Words</s2>
+    	
+	<p>
+	A word is defined either as a sequence of alphanumeric characters,
+	or a single punctuation character.
+	Words are usually separated by spaces.
+
+	<p>
+	This definition is not yet complete - e.g. the handling of
+	smileys is incorrect, but it will do for the first version.
+
+	<p>
+	Words may be inserted before any other word, or at the end
+	of a paragraph.
+
+	<p>
+	Cutting and pasting words is not terribly simple because
+	of the way people expect them to behave.
+	The following drafts are rudimentary and may be in need
+	of significant adjustment.
+
+	<p>
+	When words are cut away, 
+<pre class="algorithm">
+if the word is only punctuation,
+	do nothing.
+if there is a following space or two spaces,
+	cut them along
+else, if there is a preceding space,
+	delete it.
+</pre>
+	Deleting the preceding space seems an easier alternative than
+	having to test for it later, at paste time.
+
+	<p>
+	When words are pasted,
+<pre class="algorithm">
+if there is a space or paragraph break
+   preceding the paste location
+	paste at that location and make 
+	sure the last pasted character
+	is a space (insert if necessary)
+else if there is a space after the paste location
+	SHOULD NOT HAPPEN
+else if one of the adjacent characters is alphanumeric,
+	make sure there is a space on its side.
+</pre>
+
+	<p>
+	Except that it isn't quite that easy when punctuation 
+	is involved. This is because we need to remember where
+	the punctuation was but still leave a space.
+	If the span to be cut away starts with punctuation, cut
+	all spaces before it as well as after, but insert an extra
+	space after having cut, <b>if there was a space
+	in the end of the cut-away piece</b>. This is still
+	a bit under development...
+
+	<p>
+	Probably I should enumerate all the possible cases here...
+	Brackets are the part cut away, Parentheses are the
+	original selected part, and an asterisk means a space added
+	after the cut.
+	<pre>
+	A [(B) ]C
+	A B[(, C) ]*D
+	...
+	</pre>
+
+    <s2>Sentences</s2>
+    
+    	<p>
+	A sentence is defined as a sequence of alphanumeric characters,
+	punctuation and spaces that does not contain a double space anywhere
+	inside itself and does not start or end in a space.
+	Sentences are usually separated by double spaces, or alternatively
+	paragraph edges.
+
+	<p>
+	The choice of the double space is meaningful, but no time to
+	go into that here.
+
+	<p>
+	Sentences may be inserted before any other sentence, or at the end
+	of a paragraph.
+
+	<p>
+	When sentences are cut, cut the spaces after the last sentence along.
+	When they are pasted, make sure there are two spaces or
+	a paragraph beginning before the start.
+
+
+    <s2>Paragraphs</s2>
+
+	<p>
+	The beginning of a paragraph is marked by a special (empty) cell
+	in the Nile stream. Another cell, connected to the cell in the
+	stream tells which level of paragraph it is (H1..H6 or P, as in HTML).
+
+	<p>
+	Paragraphs may be inserted before any paragraph or at 
+	the end of the stream.
+
+	<p>
+	Cutting and pasting paragraphs is simple: 
+	when cutting, it must be from the initial marker cell,
+	up to either the end of the stream or just before another marker
+	cell. 
+	When pasting, it has to go just before another marker cell
+	or at the end of the stream, and then everything works out.
+
+<s1>Modes</s1>
+	
+	<p>
+	One of the special features of nile is that it is more 
+	explicitly aware of the nature of text than conventional 
+	word processors.
+	While e.g. recent versions of MS-Word take a mouse selection
+	to be at word boundaries by default, Nile goes much further
+	and allows the user special movement modes.
+
+	<p>
+	One of the underlying ideas (which Ted has been talking
+	about for a LONG time) here is that once a text is initially
+	written, there is a long period of rearrangement and revision --
+	often longer than the initial writing.
+	In that phase, the most of the editing actions are concerned with
+	rearranging words, phrases, sentences, paragraphs and sections.
+
+	<p>
+	However, most current programs, such as e.g. Mozilla's composer,
+	only deal with characters and force the user to exactly aim at the word
+	boundaries himself. Support for words and sentences is small;
+	double-clicking on a word selects that word but selecting two words
+	requires careful aim.  In MS-Word, selecting two words is fairly easy 
+	-- but selecting two sentences again requires more aiming.
+
+	<p>
+	Also, after selecting the part of text, we come to one of Ted's
+	favorite gripes: cut&amp;paste. To move the text to another location,
+	it will first have to be vanished from the screen and then 
+	vomited out at another location.
+
+    <s2>The Nile solution</s2>
+
+    	<p>
+	The solution used in Nile is the <dfn>hop</dfn> operation.
+	This operation, available for cells in the usual cell view
+	of GZigZag performs rearrangements such as 
+	AB<b>C</b>DE into ABD<b>C</b>E.
+
+	<p>
+	The hops happen along the natural units: when word or several
+	words are selected, they hop one word at a time, when sentence(s)
+	are selected, they hop one sentence at a time etc.
+	Of course, a super-hop operation can also be useful, which would
+	hop words a sentence at a time etc.
+
+	<p>
+	One of the reasons why hop is natural is that all text is visible
+	at all times. This is especially true in the GZigZag implementation,
+	where the infrastructure provides animation between frames.
+	So hopping a word causes a smooth animation to happen where the
+	words exchange places.  This visibility makes it easier
+	for the user to orient to the new way the text is laid out.
+	There is no abrupt rebreaking of lines either: the words which 
+	jump from one line to another also smoothly glide over.
+
+	<p>
+	It is important that the hop operation be reversible:
+	hopping left and then right should ALWAYS produce the
+	same text as the original, unless the hop left command 
+	bumped into the left edge of the document. 
+	Someone should probably go over the definitions of the word
+	operations mathematically to think about how to ensure
+	that this property works always.
+
+
+</substdims>
+
+</body>
+</html>
+
+
+
+<!--
+	vim: set syntax=html :
+-->

Documentation/Nile/nileug.wml

@@ -0,0 +1,114 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">
+<!--
+	NOTE! This file uses WML 2.0.1
+
+
+	PLEASE PLEASE PLEASE don't edit .HTML. Edit .WML!!!! Actually,
+	it's more important for you since your changes will be LOST FOREVER
+	if you edit the .HTML files.
+ -->
+
+#include "catart.wml"
+#use wml::fmt::xtable
+
+<body>
+<DOCTITLE>Nile User's Guide</DOCTITLE>
+<pre>$Id: nileug.wml,v 1.1 2000/12/09 02:29:35 tjl Exp $</pre>
+<grid layout=3x3 spacing=20>
+ <cell> <b>Tuomas J. Lukka</b> <br>
+ 	<code>lukka@iki.fi</code>
+ </cell>
+</grid>
+
+<substdims>
+
+<p>
+A short introduction to using Nile, mostly for explaining the
+keybindings.
+
+<p>
+{#MYTOC#}
+
+<s1>Warning</s1>
+
+	<p>
+	This document may be out of date. If this seems to be the case,
+	please contact the author.
+
+<s1>Keystrokes</s1>
+
+	<p>
+	Unlike most current word processors,
+	Nile has several different modes.  
+	This may seem complicated but the modes are fairly natural.
+	The most commonly used modes are the character, word and
+	sentence modes, through which the user can move with the 
+	TAB key. In these modes, the following cursor keys apply:
+
+	<!-- xtable (freetable) doesn't work with more than 10 rows
+	 (yucks!). So we split... -->
+
+	<xtable border=2 spacing=3>
+	(=,1) colspan=2
+		<b>Moving and hopping text</b>
+	(+,1) 
+	Left/Right
+		(=, 2)
+		Move the cursor
+	(+,1)
+	Shift-Left/Right
+		(=, 2)
+		Extend the cursor
+	(+,1)
+	Ctrl-Left/Right
+		(=, 2)
+		Shrink the cursor
+	(+,1)
+	Alt-Left/Right
+		(=, 2)
+		Hop the selected text
+
+	</xtable>
+
+	<xtable border=2 spacing=3> 
+	(=,1) colspan=2
+		<b>Deleting text</b>
+	(+,1)
+	Backspace
+		(=, 2)
+		Delete the previous unit.
+	(+,1)
+	Delete
+		(=, 2)
+		Delete the selected text.
+	</xtable>
+
+	<xtable border=2 spacing=3> 
+	(=,1) colspan=2
+		<b>Inserting text and changing modes</b>
+	(+,1)
+	[text]
+		(=, 2)
+		Insert the letter and move to character mode.
+
+	(+,1)
+	Enter
+		(=, 2)
+		Break the paragraph.
+	(+,1)
+	Tab
+		(=, 2)
+		Move to the next mode.
+
+	</xtable>
+
+</substdims>
+
+</body>
+</html>
+
+
+
+<!--
+	vim: set syntax=html :
+-->

Documentation/PROTOCOL

@@ -0,0 +1,192 @@
+Version 0.03 of the *active* ZZ protocol. To be used over short
+distances and reliable connections.
+
+Ascii pipe / file / ...
+
+Newlines: UNIX-style
+
+Initiation:
+
+SERV:
+	ZZ(protoversion)(uniqueservid)(serversessionid)
+CLI:
+	ZZ(protoversion)(uniqueclientid)(clientsessionid)
+
+
+Home cell is always cell id 1. id 0 does not exist. So a natural start
+would be
+
+	1 ref(1)(+1)
+
+Requests always made with reqno and may be answered out of order.
+Reqno is a simple integer.
+
+	<reqno> <reqname>(<par1>)(<par2>)...
+
+Reply:
+	<reqno> <repcode>(...
+
+E.g.
+
+CLI
+	50 getcell(24)(d.1)(+)
+SERV
+	50 cellno(40)
+
+or if no cell is there,
+	50 cellno(0)
+
+EXCEPTION:
+for get text and set text, the last parameter is a number, then newline
+and then number bytes of binary data, not followed by newline.
+
+The requests are
+
+	get(<cell from>)(<dim>)(<dir>)(<ref>)(<lock>) ---> cellno
+	gethead(<cell from>)(<dim>)(<dir>)(<ref>)(<lock>)     ---> cellno
+	sethead(<cell from>)(<dim>)(<cell>)           ---> ok
+	new(<cell from>)(<dim>)(<dir>)(<ref>)(<lock>)         ---> cellno
+	delete(<cell>)                                ---> ok
+	connect(<cell from>)(<dim>)(<other cell>)     ---> ok
+	insert(<cell from>)(<dim>)(<dir>)(<other cell>) ---> ok
+	disconnect(<cell from>)(<dim>)(<dir>)         ---> ok
+	gettext(<cell>)                               ---> text
+	settext(<cell>)(<nbytes>)                     ---> ok
+	ref(<cell>)(<ref>)                            ---> ok
+	lock(<cell>)(<lock>)                 ---> locked
+	unlock(<cell>)(<lock>)               ---> ok
+	execute(<scriptcell>)(<objcell>)(<ctrlcell>)(<viewcell>) ---> ok
+	clearerr(errorid)	---> ok
+
+And the responses:
+
+	cellno(<cell>)
+	locked(<cell>)
+	wouldblock(<cell>) --- if requested non-waiting lock didn't work
+	ok    --- no parameter
+	text(<cell>)(<nbytes>)
+	error(errorid)(errorstring)
+
+REFERENCE COUNTING AND INFORMING:
+
+The client asks the server to hold in mind that the client has n references
+to a cell and wishes to be informed about any changes. The <ref> parameter
+of the requests if for this purpose: it contains the number of references
+this client will have to the cell. When the count goes to zero,
+the server need not inform the client about changes.
+
+The ref request can be used to create more references or unreference,
+via a negative <ref>.
+
+The informing happens through the special reqno code -1:
+
+	-1 changed(<cell>)
+
+The reason for the ref parameter for all the calls that return cells
+is to avoid race conditions: getting the cell first and then referring
+allows the cell to be changed in between: e.g.
+	
+	A --- B 
+
+we know cell A and get cell B through it but before we ref it, someone
+severs the link:
+
+        A     B
+
+but since our ref request is received only after this, we never find out
+about this and assume they are still connected. Therefore, to avoid
+race conditions, the immediate ref:ing is possible.
+
+Since the client can't otherwise behave correctly, there is a special
+code when the cell is deleted:
+
+	-1 deleted(<cell>)
+
+since otherwise the client might try to get neighbours of the deleted
+cell.
+
+LOCKING
+
+The <lock> parameter represents the number of locks this process
+wants on the cell - generally 1.
+The lock does NOT preclude any other client from doing anything but only
+stops others from locking the cell. Locks can be requested synchronously
+or asynchronously, in three different ways:
+
+	1. lock = "1" -> tries to lock, returns wouldblock if can't
+	2. lock = "1w" -> tries to lock, waits until can lock. DEADLOCK DANGER
+	3. lock = "1a" -> tries to lock, sends the locked command 
+	only once the lock is obtained - the other results of the request
+	will keep going.
+
+A server has the right not to support any locking --- it is possible
+to put a protocol filter on top of it that does.
+
+
+
+ERRORS
+
+If it is likely that two processes would modify the same cells, they should
+agree to lock the cells. In that case, the fastest processing times would
+be achieved through performing all these operations in one row:
+
+	lock(50)(1w)
+	new(50)... # operate
+	unlock(50)
+
+Because of this, there needs to be a way of performing a series of
+operations but only if all of them are successful. Therefore, after
+sending an error, the server will wait for the clearerr command and
+ignore all the commands before it. Since the error has the number of the
+request in front of the command, the client will be aware of what has happened.
+
+This way many useless context switches can be avoided.
+
+
+
+=======================================
+PROPOSAL: New change op.
+Idea from Benjamin Fallenstein.
+
+Instead of new, delete, connect, insert, disconnect, settext you would
+simply have one command to upload a fragment of zzspace, possibly identified
+with a current fragment.
+
+So 
+	uploadfrag
+	curcell(O<curid>)
+	delcell(<curid>)
+	newcell(N<id>)
+	connection(<ONid>)(<dim>)(<dir>)(<ONid>)
+	endupload
+
+where ONid is O<curid>, N<id> or 0.
+
+Thus, disconnect(15, d.1, +) would be
+
+	uploadfrag
+	curcell(Ocell)
+	connection(Ocell)(d.1)(+)(0)
+	endupload
+
+and insert(f, d.1, +, w) where the next cell after f is g, is
+
+	uploadfrag
+	curcell(Of)
+	curcell(Og)
+	curcell(Ow)
+	connection(Of)(d.1)(+)(Ow)
+	connection(Ow)(d.1)(+)(Og)
+	endupload
+
+By default, all the other connections remain.
+
+OTOH, insert is a nice primitive operation for many things, like cursors....
+On the other hand, an operation like jump is dangerous to synchronize
+otherwise, implemented using the above connect operation.
+
+An uploadfrag can be guaranteed to be atomic... this + locking begins
+sounding good.
+
+- keep insert and uploadfrag, discard others?
+

Documentation/README

@@ -0,0 +1,55 @@
+NOTE: do contact the author (lukka@iki.fi for most of the stuff) if
+there is an unfinished part that you really need - I sometimes need
+prodding to get things finished. Comments are also appreciated.
+
+NOTE 2: 
+THE SUBDIRECTORIES THAT ARE CURRENTLY BEING ACTIVELY WRITTEN ARE
+CyberText, DesignProblems and Spec. THE OTHERS ARE A BIT STALE.
+
+I recommend starting with the Gentle_Introduction and then working your
+way through the others if the subject matters interests you (for example,
+if you are not hacking the internals, CellScroll will not be interesting
+to you).
+
+Some of the documents are written in LaTeX using gpic to compile 
+diagrams (since it seems more reasonable than e.g. xypic or any
+picture language I've seen for LaTeX). See the Makefile for how
+the process is supposed to go. The LaTeX files also use rcs.sty,
+which is available in the Debian linux package rcs-latex, but also
+probably from CTAN. I'm planning to put up autogenerated PostScript 
+files of these Real Soon Now.
+
+The files in this directory:
+
+Gentle_Introduction/
+	an introduction to what ZigZag is and how it works.
+
+Clang_Design/
+	Clang is a language for writing programs using the ZigZag
+	structure... no, better to say: Clang is a way of interpreting
+	a certain kind of ZigZag structure as a program.
+	This document discusses the various issues at stake when 
+	designing Clang.
+
+CellScroll/
+	CellScrolls are a way to store both the current state
+	and all former states of a ZigZag space.
+
+Interfacing/
+
+misc/
+	odds and ends
+
+DimBased/
+	Some thoughs on reorganization of the model to think about ZZ 
+	in the code to be based on dimensions, not so much cells.
+
+PROTOCOL
+	ASCII description of the ZZ network protocol. Don't rely on this:
+	use the source, Luke.
+
+	The protocol needs some rethinking anyway.
+
+wmlinc/
+	Some include files used in the WML (website modeling language)
+	files around.

Documentation/STARTING

@@ -0,0 +1,24 @@
+$Id: STARTING,v 1.2 2000/09/09 13:37:32 tjl Exp $
+
+Documenting how to start with GZigZag is difficult because it
+is a moving target. So if there are any discrepancies with the
+current CVS version and this document, please ask me (lukka@iki.fi)
+to update it.
+Especially the keystrokes are liable to change soon. This is the situation 
+at the date given above.
+
+When you first start GZigZag, you get two windows showing cells and
+their connections.
+The system works so that
+you click on the right-hand window to focus on it and then all you need
+is the keyboard: you can forget the mouse (it does work though: clicking
+on a cell moves to it).
+
+For the cursor motion you have the keys "IJL," and "ESFC". Pressing Tab
+will give you a text insertion cursor that you can move sideways with the
+arrow keys.
+
+Other commands are n-<dir> for new cell, / (slash)-<dir> for connecting
+two cells etc. They are shown in the user's guide.
+
+Any other questions, just mail me.

Documentation/Slices/SliceLogic

@@ -0,0 +1,179 @@
+Date: Tue, 14 Jul 1998 19:35:41 +0900
+To: zzdev@xanadu.net
+From: Ted Nelson <ted@xanadu.net>
+Subject: :zz: ZigZag Design Notes: SLICE LOGIC 1  (d6
+Cc: ted
+
+zzSliceLogic.d6
+98.07.14
+
+[illustration accompanying this email: zzSliceLogic.bmp]
+
+SLICE LOGIC 1
+
+The main objective of the ZigZag Slice system is to be able to combine
+pieces of zzstructure.  Relatively fixed material (ends of rows, ends of
+columns, titles) are expected to stay in RAM, with other stuff coming and
+going.
+
+Further objectives: 
+- to limit RAM usage without going to some system of virtual memory
+- to allow the user to select the portions being worked on
+- to allow slices to slide into the middle of other slices according to the
+user's desire.  (Thus slices should be connectable anywhere, even in the
+middle of ranks.)
+
+MANY logics and rule-sets are possible for this.  I have thought about this
+for some years.  
+
+What follows is the simplest method I could work out that does the job
+neatly.  It is called "Slice Logic 1" because it's the easy one that I
+think we should implement first.  (Last week I produced a document with a
+more complex system, possibly for implementation later, and quite
+interesting technically-- I think-- but I want you to see this one first.)  
+
+This system need not be implemented all at once.  For instance, we can
+forbid Part II at first.  
+
+- - - - -
+PART 0.  SKIP ON FIRST READING.
+
+0000.  (If a rank has a leading edge, it cannot be a ringrank and
+necessarily has a trailing edge.)  
+
+000.  ASSUME that the user can neatly divide the world into slices.
+Slices, like dimensions, may have any names, but with a prefix: slices
+begin with "s.".  Lexical order thereafter will be significant.  
+
+
+00.  There may be a d.slice and d.slicelist, not discussed here.
+(Eventually-- or now if there is a need-- the list of slices can be
+maintained along d.slice, and the cells of a slice can be connected on a
+list in d.slicelist.  Still under consideration.)  
+
+- - - - -
+PART I.  PREFLET LOGIC.
+
+0.  A ZigZag slice is a data set with cells which may be connected to each
+other in the ordinary ZZ way.  But not necessarily; there may also be loose
+cells in the slice.  
+
+1.  Slice 0  (s.0) is always resident.
+
+Other slices may be called in as needed.  
+
+2.  Slices are independent structures.  CONNECTIONS BETWEEN SLICES ARE NOT
+OF THE USUAL KIND, with doubly-linked cells.  Instead, they have
+*preferred* points of attachment.
+
+3.  PREFERENCE OF ATTACHMENT IS EXPRESSED BY MEANS OF A 'PREFLET'-- a piece
+of information in the cell specifying a cell in another slice to which it
+would *like* to be attached, negward, in a specified dimension.  
+
+In the current design, a cell may have only one preflet in a given
+dimension.  
+
+4.  The process of resolving preflets determines the way in which the
+slices are attached.  However, once attached, the slices are stitched
+together doubly-linked in RAM somehow as ordinary zzcells.  (Implementation
+is not significant; eventually different slices should be storable by
+different databases or other methods.)  
+
+5.  When a slice is brought in, only the preflets of its leading edge-- all
+the negend cells-- are considered.  (This could be done thusly: test all
+cells to see if they are negends; test all negends for preflets.)
+
+6.  Any cell with a preflet for a cell already resident, and not contested
+by any other cell's preflet, gets to insert/attach itself to the specified
+cell.
+
+7.  If a cell has a preflet for a cell which is not currently resident, the
+preflet is ignored. 
+
+8. Two cells may have to be separated to honor a preflet specifying one of
+them.  These two cells will rejoin when the slice is swapped out, if
+appropriate.  
+
+IF THEY HAVE A LOCKED LINK (not yet implemented), they may not be separated.
+
+9.  If two leading cells in two slices both have a preflet for the same
+cell in another slice which is resident, the slice with lower lexical order
+wins-- and the second slice attaches itself *indirectly*, to the trailing
+edge (posend) of the winning cell's rank.  See illustration.
+
+10.  If two leading cells in the same slice A have a preflet for the same
+cell in a second slice B which is resident, the slice with lexically lower
+cellname wins-- and the second slice attaches itself *indirectly*, to the
+trailing edge (posend) of the winning cell's rank.  See illustration.
+(This would probably lead to the two ranks in A later becoming a single
+rank, due to rule 12.)
+
+11.  Whenever a slice is swapped in or out, the preflets of all current
+slices must be resolved again.
+
+12.  Whenever a slice is swapped out, its detached negends are given
+preflets again.  These preflets will normally be to the cells from which
+the cell has just been detached in s.0-- either directly or indirectly.
+
+13.  If swapping a slice out severs a rank in some other slice (usually
+s.0), that rank is reconnected where the swapped-out cells have just been
+taken away.  (This will re-attach cells which were separated by the
+incoming slice, unless they have been moved.)
+
+- - - - -
+EXAMPLE.
+
+Consider the illustration.  Assume that the x-axis is d.1 and the y-axis is
+d.2.  
+
+Not shown is s.0, which contains cells 16, 42, 131, 265 and 22.  These are
+not necessarily negends. 
+
+Shown are two slices, s.2 and s.4.  They have leading-edge preflets for
+some of the same cells in s.0.
+
+The preflets for 13 and 22 take effect without conflict.  What follows is
+about resolving the others.
+
+Both s.2 and s.4 have a leading-edge preflet in d.2 for cell 16.  s.0 wins.
+ The cell in s.4 with a preflet for 16 connects to the *trailing* edge of
+the same rank in s.2 (cell 68).  
+
+Similarly, both slices share a preflet for cell 42 in d.2.  s.2 wins, and
+s.4 connects to the trailing cell in the same rank, cell 4.
+
+Similarly, both slices share a preflet for cell 265 in d.1.  s.2 wins, and
+s.4 connects to the trailing cell in the same rank, cell 31.
+
+If s.2 is swapped out, preflets are considered again at the leading edges
+of all slices (except s.0).  Thus s.4's preflets for 16, 42 and 265 then
+cause them to be directly attached to 16, 42 and 265.
+
+If s.4 is then swapped out, each rank of s.4 which is extracted from within
+a rank in s.0 causes that rank in s.0 to be reconnected.
+
+- - - - -
+PART TWO: CROSSING OF CELLS BETWEEN SLICES.  (May be disallowed in Phase 1.)  
+
+13.  (The user somehow knows where the slice boundaries are.)
+
+14.  If a cell is moved / hopped / connected into a different slice, and
+has *no* other connections to its former slice, all its contents are moved.
+ The information that travels with it includes its contents, processor of
+origin, cell of origin, and which slice the cell of origin is on.
+
+15.  If a cell is moved / hopped / connected / cloned into a different
+slice,  and retains connections to its former slice, a Remote Clone is
+made.  The information that travels with it includes its contents,
+processor of origin, cell of origin, and which slice the cell of origin is on.
+
+16.  When a cell is swapped in, Remote Clones must be resolved.
+
+If a Remote Clone's connections in all slices are consistent with each
+other, it is considered to be one with its origin, and they are shown as
+only one cell.  However, if they are inconsistent-- more than one
+connection posward or negative in a given dimension-- the second instance
+is deemed to be a clone.  After each operation its connections should be
+checked for compressibility to one cell.  
+
+

Documentation/Spec/Makefile

@@ -0,0 +1,15 @@
+# DIAGRAMS=linkorder.png beamorder.png
+DIAGRAMS=cursor1.png cursordim.png canvasraster.png rasterspec.png \
+	inheritparam.png
+DEP=../wmlinc/article.wml
+
+all : zzspec.html zzspec-ns4.html
+
+zzspec.html: zzspec.wml ../keybindings.wml $(DIAGRAMS) $(DEP)
+
+zzspec-ns4.html: zzspec.wml ../keybindings.wml $(DIAGRAMS) $(DEP)
+
+include ../lib.mk
+
+
+

Documentation/Spec/canvasraster.dia

@@ -0,0 +1,427 @@
+<?xml version="1.0"?>
+<diagram xmlns:dia="http://www.lysator.liu.se/~alla/dia/">
+  <diagramdata>
+    <attribute name="background">
+      <color val="#ffffff"/>
+    </attribute>
+    <attribute name="paper">
+      <composite type="paper">
+        <attribute name="name">
+          <string>#A4#</string>
+        </attribute>
+        <attribute name="tmargin">
+          <real val="2.82"/>
+        </attribute>
+        <attribute name="bmargin">
+          <real val="2.82"/>
+        </attribute>
+        <attribute name="lmargin">
+          <real val="2.82"/>
+        </attribute>
+        <attribute name="rmargin">
+          <real val="2.82"/>
+        </attribute>
+        <attribute name="is_portrait">
+          <boolean val="true"/>
+        </attribute>
+        <attribute name="scaling">
+          <real val="1"/>
+        </attribute>
+        <attribute name="fitto">
+          <boolean val="false"/>
+        </attribute>
+      </composite>
+    </attribute>
+  </diagramdata>
+  <layer name="Background" visible="true">
+    <object type="Standard - Box" version="0" id="O0">
+      <attribute name="obj_pos">
+        <point val="12.5,1.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="12.45,1.45;17,3.05"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="12.5,1.5"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="4.45"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O1">
+      <attribute name="obj_pos">
+        <point val="14.5,2.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="12.279,1.7069;16.721,2.7069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#viewspx#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="14.5,2.5"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O2">
+      <attribute name="obj_pos">
+        <point val="12.5,9"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="12.45,8.95;17,10.55"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="12.5,9"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="4.45"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O3">
+      <attribute name="obj_pos">
+        <point val="12.5,6.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="12.45,6.45;19.55,8.05"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="12.5,6.5"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="7"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O4">
+      <attribute name="obj_pos">
+        <point val="12.5,4"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="12.45,3.95;17,5.55"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="12.5,4"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="4.45"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Line" version="0" id="O5">
+      <attribute name="obj_pos">
+        <point val="14.725,3"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="13.875,2.15;15.575,4.85"/>
+      </attribute>
+      <attribute name="conn_endpoints">
+        <point val="14.725,3"/>
+        <point val="14.725,4"/>
+      </attribute>
+      <attribute name="numcp">
+        <int val="1"/>
+      </attribute>
+      <attribute name="end_arrow">
+        <enum val="3"/>
+      </attribute>
+      <attribute name="end_arrow_length">
+        <real val="0.8"/>
+      </attribute>
+      <attribute name="end_arrow_width">
+        <real val="0.8"/>
+      </attribute>
+      <connections>
+        <connection handle="0" to="O0" connection="6"/>
+        <connection handle="1" to="O4" connection="1"/>
+      </connections>
+    </object>
+    <object type="Standard - Line" version="0" id="O6">
+      <attribute name="obj_pos">
+        <point val="14.725,5.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="13.875,4.65;15.85,7.35"/>
+      </attribute>
+      <attribute name="conn_endpoints">
+        <point val="14.725,5.5"/>
+        <point val="15,6.5"/>
+      </attribute>
+      <attribute name="numcp">
+        <int val="1"/>
+      </attribute>
+      <attribute name="end_arrow">
+        <enum val="3"/>
+      </attribute>
+      <attribute name="end_arrow_length">
+        <real val="0.8"/>
+      </attribute>
+      <attribute name="end_arrow_width">
+        <real val="0.8"/>
+      </attribute>
+      <connections>
+        <connection handle="0" to="O4" connection="6"/>
+      </connections>
+    </object>
+    <object type="Standard - Line" version="0" id="O7">
+      <attribute name="obj_pos">
+        <point val="15,8"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="13.875,7.15;15.85,9.85"/>
+      </attribute>
+      <attribute name="conn_endpoints">
+        <point val="15,8"/>
+        <point val="14.725,9"/>
+      </attribute>
+      <attribute name="numcp">
+        <int val="1"/>
+      </attribute>
+      <attribute name="end_arrow">
+        <enum val="3"/>
+      </attribute>
+      <attribute name="end_arrow_length">
+        <real val="0.8"/>
+      </attribute>
+      <attribute name="end_arrow_width">
+        <real val="0.8"/>
+      </attribute>
+      <connections>
+        <connection handle="1" to="O2" connection="1"/>
+      </connections>
+    </object>
+    <object type="Standard - Text" version="0" id="O8">
+      <attribute name="obj_pos">
+        <point val="16,7.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="12.264,6.7069;19.736,7.7069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#CanvasRaster#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="16,7.5"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - BezierLine" version="0" id="O9">
+      <attribute name="obj_pos">
+        <point val="12.5,7.25"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="4.15,-0.85;13.35,15.35"/>
+      </attribute>
+      <attribute name="bez_points">
+        <point val="12.5,7.25"/>
+        <point val="10.5,0"/>
+        <point val="5,14.5"/>
+        <point val="6.45,3"/>
+      </attribute>
+      <attribute name="corner_types">
+        <enum val="0"/>
+        <enum val="0"/>
+      </attribute>
+      <attribute name="end_arrow">
+        <enum val="3"/>
+      </attribute>
+      <attribute name="end_arrow_length">
+        <real val="0.8"/>
+      </attribute>
+      <attribute name="end_arrow_width">
+        <real val="0.8"/>
+      </attribute>
+      <connections>
+        <connection handle="0" to="O3" connection="3"/>
+        <connection handle="3" to="O11" connection="7"/>
+      </connections>
+    </object>
+    <object type="Standard - Text" version="0" id="O10">
+      <attribute name="obj_pos">
+        <point val="6,9"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="1.658,8.2069;10.342,11.2069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#d.cursor-cargo
+and
+d.cursor#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="6,9"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O11">
+      <attribute name="obj_pos">
+        <point val="2,1.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="1.95,1.45;6.5,3.05"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="2,1.5"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="4.45"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O12">
+      <attribute name="obj_pos">
+        <point val="4,2.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="3.597,1.7069;4.403,2.7069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#R#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="4,2.5"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Line" version="0" id="O13">
+      <attribute name="obj_pos">
+        <point val="20,2"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="19.15,1.15;20.85,10.85"/>
+      </attribute>
+      <attribute name="conn_endpoints">
+        <point val="20,2"/>
+        <point val="20,10"/>
+      </attribute>
+      <attribute name="numcp">
+        <int val="1"/>
+      </attribute>
+      <attribute name="end_arrow">
+        <enum val="3"/>
+      </attribute>
+      <attribute name="end_arrow_length">
+        <real val="0.8"/>
+      </attribute>
+      <attribute name="end_arrow_width">
+        <real val="0.8"/>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O14">
+      <attribute name="obj_pos">
+        <point val="21.5,6"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="20.491,5.2069;22.509,6.2069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#d.2#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="21.5,6"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+  </layer>
+</diagram>

Documentation/Spec/cursor1.dia

@@ -0,0 +1,590 @@
+<?xml version="1.0"?>
+<diagram xmlns:dia="http://www.lysator.liu.se/~alla/dia/">
+  <diagramdata>
+    <attribute name="background">
+      <color val="#ffffff"/>
+    </attribute>
+    <attribute name="paper">
+      <composite type="paper">
+        <attribute name="name">
+          <string>#A4#</string>
+        </attribute>
+        <attribute name="tmargin">
+          <real val="2.82"/>
+        </attribute>
+        <attribute name="bmargin">
+          <real val="2.82"/>
+        </attribute>
+        <attribute name="lmargin">
+          <real val="2.82"/>
+        </attribute>
+        <attribute name="rmargin">
+          <real val="2.82"/>
+        </attribute>
+        <attribute name="is_portrait">
+          <boolean val="true"/>
+        </attribute>
+        <attribute name="scaling">
+          <real val="1"/>
+        </attribute>
+        <attribute name="fitto">
+          <boolean val="false"/>
+        </attribute>
+      </composite>
+    </attribute>
+  </diagramdata>
+  <layer name="Background" visible="true">
+    <object type="Standard - Box" version="0" id="O0">
+      <attribute name="obj_pos">
+        <point val="13.5,6"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="13.45,5.95;18,7.55"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="13.5,6"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="4.45"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O1">
+      <attribute name="obj_pos">
+        <point val="1.5,6"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="1.45,5.95;6,7.5"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="1.5,6"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="4.45"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.45"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O2">
+      <attribute name="obj_pos">
+        <point val="7.5,6"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="7.45,5.95;12,7.5"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="7.5,6"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="4.45"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.45"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O3">
+      <attribute name="obj_pos">
+        <point val="1.5,3.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="1.45,3.45;6,5"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="1.5,3.5"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="4.45"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.45"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O4">
+      <attribute name="obj_pos">
+        <point val="1.5,1"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="1.45,0.95;6,2.5"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="1.5,1"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="4.45"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.45"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O5">
+      <attribute name="obj_pos">
+        <point val="15.5,7"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="13.279,6.2069;17.721,7.2069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#viewspx#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="15.5,7"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O6">
+      <attribute name="obj_pos">
+        <point val="3.5,2"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="3.097,1.2069;3.903,2.2069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#A#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="3.5,2"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O7">
+      <attribute name="obj_pos">
+        <point val="4,7"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="4,6.2069;4,7.2069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>##</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="4,7"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O8">
+      <attribute name="obj_pos">
+        <point val="3.5,7"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="3.097,6.2069;3.903,7.2069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#C#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="3.5,7"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Line" version="0" id="O9">
+      <attribute name="obj_pos">
+        <point val="5.95,6.725"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="5.1,5.875;8.35,7.575"/>
+      </attribute>
+      <attribute name="conn_endpoints">
+        <point val="5.95,6.725"/>
+        <point val="7.5,6.725"/>
+      </attribute>
+      <attribute name="numcp">
+        <int val="1"/>
+      </attribute>
+      <attribute name="end_arrow">
+        <enum val="3"/>
+      </attribute>
+      <attribute name="end_arrow_length">
+        <real val="0.8"/>
+      </attribute>
+      <attribute name="end_arrow_width">
+        <real val="0.8"/>
+      </attribute>
+      <connections>
+        <connection handle="0" to="O1" connection="4"/>
+        <connection handle="1" to="O2" connection="3"/>
+      </connections>
+    </object>
+    <object type="Standard - Line" version="0" id="O10">
+      <attribute name="obj_pos">
+        <point val="3.5,5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="2.65,4.15;4.35,6.85"/>
+      </attribute>
+      <attribute name="conn_endpoints">
+        <point val="3.5,5"/>
+        <point val="3.5,6"/>
+      </attribute>
+      <attribute name="numcp">
+        <int val="1"/>
+      </attribute>
+      <attribute name="end_arrow">
+        <enum val="3"/>
+      </attribute>
+      <attribute name="end_arrow_length">
+        <real val="0.8"/>
+      </attribute>
+      <attribute name="end_arrow_width">
+        <real val="0.8"/>
+      </attribute>
+    </object>
+    <object type="Standard - Line" version="0" id="O11">
+      <attribute name="obj_pos">
+        <point val="3.5,2.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="2.65,1.65;4.35,4.35"/>
+      </attribute>
+      <attribute name="conn_endpoints">
+        <point val="3.5,2.5"/>
+        <point val="3.5,3.5"/>
+      </attribute>
+      <attribute name="numcp">
+        <int val="1"/>
+      </attribute>
+      <attribute name="end_arrow">
+        <enum val="3"/>
+      </attribute>
+      <attribute name="end_arrow_length">
+        <real val="0.8"/>
+      </attribute>
+      <attribute name="end_arrow_width">
+        <real val="0.8"/>
+      </attribute>
+    </object>
+    <object type="Standard - Line" version="0" id="O12">
+      <attribute name="obj_pos">
+        <point val="11.95,6.725"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="11.1,5.875;14.35,7.6"/>
+      </attribute>
+      <attribute name="conn_endpoints">
+        <point val="11.95,6.725"/>
+        <point val="13.5,6.75"/>
+      </attribute>
+      <attribute name="numcp">
+        <int val="1"/>
+      </attribute>
+      <attribute name="end_arrow">
+        <enum val="3"/>
+      </attribute>
+      <attribute name="end_arrow_length">
+        <real val="0.8"/>
+      </attribute>
+      <attribute name="end_arrow_width">
+        <real val="0.8"/>
+      </attribute>
+      <connections>
+        <connection handle="0" to="O2" connection="4"/>
+        <connection handle="1" to="O0" connection="3"/>
+      </connections>
+    </object>
+    <object type="Standard - Line" version="0" id="O13">
+      <attribute name="obj_pos">
+        <point val="7.5,1"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="6.65,0.15;8.35,5.85"/>
+      </attribute>
+      <attribute name="conn_endpoints">
+        <point val="7.5,1"/>
+        <point val="7.5,5"/>
+      </attribute>
+      <attribute name="numcp">
+        <int val="1"/>
+      </attribute>
+      <attribute name="end_arrow">
+        <enum val="3"/>
+      </attribute>
+      <attribute name="end_arrow_length">
+        <real val="0.8"/>
+      </attribute>
+      <attribute name="end_arrow_width">
+        <real val="0.8"/>
+      </attribute>
+    </object>
+    <object type="Standard - Line" version="0" id="O14">
+      <attribute name="obj_pos">
+        <point val="10.5,5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="9.65,4.15;17.85,5.85"/>
+      </attribute>
+      <attribute name="conn_endpoints">
+        <point val="10.5,5"/>
+        <point val="17,5"/>
+      </attribute>
+      <attribute name="numcp">
+        <int val="1"/>
+      </attribute>
+      <attribute name="end_arrow">
+        <enum val="3"/>
+      </attribute>
+      <attribute name="end_arrow_length">
+        <real val="0.8"/>
+      </attribute>
+      <attribute name="end_arrow_width">
+        <real val="0.8"/>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O15">
+      <attribute name="obj_pos">
+        <point val="10,2"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="7.476,1.2069;12.524,2.2069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#d.cursor#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="10,2"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O16">
+      <attribute name="obj_pos">
+        <point val="14,4"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="9.658,3.2069;18.342,4.2069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#d.cursor-cargo#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="14,4"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O17">
+      <attribute name="obj_pos">
+        <point val="9.5,6.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="9.5,5.7069;9.5,6.7069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>##</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="9.5,6.5"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O18">
+      <attribute name="obj_pos">
+        <point val="9.5,7"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="8.491,6.2069;10.509,7.2069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#...#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="9.5,7"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O19">
+      <attribute name="obj_pos">
+        <point val="3.5,4.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="2.491,3.7069;4.509,4.7069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#...#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="3.5,4.5"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O20">
+      <attribute name="obj_pos">
+        <point val="10,14"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="10,13.2069;10,14.2069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>##</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="10,14"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+  </layer>
+</diagram>

Documentation/Spec/cursordim.dia

@@ -0,0 +1,769 @@
+<?xml version="1.0"?>
+<diagram xmlns:dia="http://www.lysator.liu.se/~alla/dia/">
+  <diagramdata>
+    <attribute name="background">
+      <color val="#ffffff"/>
+    </attribute>
+    <attribute name="paper">
+      <composite type="paper">
+        <attribute name="name">
+          <string>#A4#</string>
+        </attribute>
+        <attribute name="tmargin">
+          <real val="2.82"/>
+        </attribute>
+        <attribute name="bmargin">
+          <real val="2.82"/>
+        </attribute>
+        <attribute name="lmargin">
+          <real val="2.82"/>
+        </attribute>
+        <attribute name="rmargin">
+          <real val="2.82"/>
+        </attribute>
+        <attribute name="is_portrait">
+          <boolean val="true"/>
+        </attribute>
+        <attribute name="scaling">
+          <real val="1"/>
+        </attribute>
+        <attribute name="fitto">
+          <boolean val="false"/>
+        </attribute>
+      </composite>
+    </attribute>
+  </diagramdata>
+  <layer name="Background" visible="true">
+    <object type="Standard - Box" version="0" id="O0">
+      <attribute name="obj_pos">
+        <point val="18.5,6"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="18.45,5.95;23,7.55"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="18.5,6"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="4.45"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O1">
+      <attribute name="obj_pos">
+        <point val="1.5,6"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="1.45,5.95;6,7.5"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="1.5,6"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="4.45"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.45"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O2">
+      <attribute name="obj_pos">
+        <point val="7.5,6"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="7.45,5.95;12,7.5"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="7.5,6"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="4.45"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.45"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O3">
+      <attribute name="obj_pos">
+        <point val="1.5,3.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="1.45,3.45;6,5"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="1.5,3.5"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="4.45"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.45"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O4">
+      <attribute name="obj_pos">
+        <point val="1.5,1"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="1.45,0.95;6,2.5"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="1.5,1"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="4.45"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.45"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O5">
+      <attribute name="obj_pos">
+        <point val="20.5,7"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="20.097,6.2069;20.903,7.2069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#Y#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="20.5,7"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O6">
+      <attribute name="obj_pos">
+        <point val="3.5,2"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="3.097,1.2069;3.903,2.2069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#A#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="3.5,2"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O7">
+      <attribute name="obj_pos">
+        <point val="4,7"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="4,6.2069;4,7.2069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>##</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="4,7"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O8">
+      <attribute name="obj_pos">
+        <point val="3.5,7"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="3.097,6.2069;3.903,7.2069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#C#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="3.5,7"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Line" version="0" id="O9">
+      <attribute name="obj_pos">
+        <point val="5.95,6.725"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="5.1,5.875;8.35,7.575"/>
+      </attribute>
+      <attribute name="conn_endpoints">
+        <point val="5.95,6.725"/>
+        <point val="7.5,6.725"/>
+      </attribute>
+      <attribute name="numcp">
+        <int val="1"/>
+      </attribute>
+      <attribute name="end_arrow">
+        <enum val="3"/>
+      </attribute>
+      <attribute name="end_arrow_length">
+        <real val="0.8"/>
+      </attribute>
+      <attribute name="end_arrow_width">
+        <real val="0.8"/>
+      </attribute>
+      <connections>
+        <connection handle="0" to="O1" connection="4"/>
+        <connection handle="1" to="O2" connection="3"/>
+      </connections>
+    </object>
+    <object type="Standard - Line" version="0" id="O10">
+      <attribute name="obj_pos">
+        <point val="3.5,5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="2.65,4.15;4.35,6.85"/>
+      </attribute>
+      <attribute name="conn_endpoints">
+        <point val="3.5,5"/>
+        <point val="3.5,6"/>
+      </attribute>
+      <attribute name="numcp">
+        <int val="1"/>
+      </attribute>
+      <attribute name="end_arrow">
+        <enum val="3"/>
+      </attribute>
+      <attribute name="end_arrow_length">
+        <real val="0.8"/>
+      </attribute>
+      <attribute name="end_arrow_width">
+        <real val="0.8"/>
+      </attribute>
+    </object>
+    <object type="Standard - Line" version="0" id="O11">
+      <attribute name="obj_pos">
+        <point val="3.5,2.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="2.65,1.65;4.35,4.35"/>
+      </attribute>
+      <attribute name="conn_endpoints">
+        <point val="3.5,2.5"/>
+        <point val="3.5,3.5"/>
+      </attribute>
+      <attribute name="numcp">
+        <int val="1"/>
+      </attribute>
+      <attribute name="end_arrow">
+        <enum val="3"/>
+      </attribute>
+      <attribute name="end_arrow_length">
+        <real val="0.8"/>
+      </attribute>
+      <attribute name="end_arrow_width">
+        <real val="0.8"/>
+      </attribute>
+    </object>
+    <object type="Standard - Line" version="0" id="O12">
+      <attribute name="obj_pos">
+        <point val="11.95,6.725"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="11.1,5.875;19.35,7.6"/>
+      </attribute>
+      <attribute name="conn_endpoints">
+        <point val="11.95,6.725"/>
+        <point val="18.5,6.75"/>
+      </attribute>
+      <attribute name="numcp">
+        <int val="1"/>
+      </attribute>
+      <attribute name="end_arrow">
+        <enum val="3"/>
+      </attribute>
+      <attribute name="end_arrow_length">
+        <real val="0.8"/>
+      </attribute>
+      <attribute name="end_arrow_width">
+        <real val="0.8"/>
+      </attribute>
+      <connections>
+        <connection handle="0" to="O2" connection="4"/>
+        <connection handle="1" to="O0" connection="3"/>
+      </connections>
+    </object>
+    <object type="Standard - Line" version="0" id="O13">
+      <attribute name="obj_pos">
+        <point val="10.5,5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="9.65,4.15;17.85,5.85"/>
+      </attribute>
+      <attribute name="conn_endpoints">
+        <point val="10.5,5"/>
+        <point val="17,5"/>
+      </attribute>
+      <attribute name="numcp">
+        <int val="1"/>
+      </attribute>
+      <attribute name="end_arrow">
+        <enum val="3"/>
+      </attribute>
+      <attribute name="end_arrow_length">
+        <real val="0.8"/>
+      </attribute>
+      <attribute name="end_arrow_width">
+        <real val="0.8"/>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O14">
+      <attribute name="obj_pos">
+        <point val="10,2"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="7.476,1.2069;12.524,2.2069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#d.cursor#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="10,2"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O15">
+      <attribute name="obj_pos">
+        <point val="14,4"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="9.658,3.2069;18.342,4.2069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#d.cursor-cargo#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="14,4"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O16">
+      <attribute name="obj_pos">
+        <point val="9.5,6.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="9.5,5.7069;9.5,6.7069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>##</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="9.5,6.5"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O17">
+      <attribute name="obj_pos">
+        <point val="9.5,7"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="8.491,6.2069;10.509,7.2069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#...#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="9.5,7"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O18">
+      <attribute name="obj_pos">
+        <point val="3.5,4.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="2.491,3.7069;4.509,4.7069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#...#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="3.5,4.5"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O19">
+      <attribute name="obj_pos">
+        <point val="9.5,12"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="9.45,11.95;14,13.55"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="9.5,12"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="4.45"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O20">
+      <attribute name="obj_pos">
+        <point val="11.5,13"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="9.279,12.2069;13.721,13.2069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#viewspx#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="11.5,13"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O21">
+      <attribute name="obj_pos">
+        <point val="14,9"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="13.95,8.95;18.5,10.55"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="14,9"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="4.45"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O22">
+      <attribute name="obj_pos">
+        <point val="16,10"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="15.597,9.2069;16.403,10.2069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#X#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="16,10"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Line" version="0" id="O23">
+      <attribute name="obj_pos">
+        <point val="11.725,12"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="10.875,9.65;14.85,12.85"/>
+      </attribute>
+      <attribute name="conn_endpoints">
+        <point val="11.725,12"/>
+        <point val="14,10.5"/>
+      </attribute>
+      <attribute name="numcp">
+        <int val="1"/>
+      </attribute>
+      <attribute name="end_arrow">
+        <enum val="3"/>
+      </attribute>
+      <attribute name="end_arrow_length">
+        <real val="0.8"/>
+      </attribute>
+      <attribute name="end_arrow_width">
+        <real val="0.8"/>
+      </attribute>
+      <connections>
+        <connection handle="0" to="O19" connection="1"/>
+        <connection handle="1" to="O21" connection="5"/>
+      </connections>
+    </object>
+    <object type="Standard - Line" version="0" id="O24">
+      <attribute name="obj_pos">
+        <point val="16,9"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="15.15,6.65;19.35,9.85"/>
+      </attribute>
+      <attribute name="conn_endpoints">
+        <point val="16,9"/>
+        <point val="18.5,7.5"/>
+      </attribute>
+      <attribute name="numcp">
+        <int val="1"/>
+      </attribute>
+      <attribute name="end_arrow">
+        <enum val="3"/>
+      </attribute>
+      <attribute name="end_arrow_length">
+        <real val="0.8"/>
+      </attribute>
+      <attribute name="end_arrow_width">
+        <real val="0.8"/>
+      </attribute>
+      <connections>
+        <connection handle="1" to="O0" connection="5"/>
+      </connections>
+    </object>
+    <object type="Standard - Line" version="0" id="O25">
+      <attribute name="obj_pos">
+        <point val="20.5,6"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="19.65,3.65;23.35,6.85"/>
+      </attribute>
+      <attribute name="conn_endpoints">
+        <point val="20.5,6"/>
+        <point val="22.5,4.5"/>
+      </attribute>
+      <attribute name="numcp">
+        <int val="1"/>
+      </attribute>
+      <attribute name="end_arrow">
+        <enum val="3"/>
+      </attribute>
+      <attribute name="end_arrow_length">
+        <real val="0.8"/>
+      </attribute>
+      <attribute name="end_arrow_width">
+        <real val="0.8"/>
+      </attribute>
+    </object>
+    <object type="Standard - Line" version="0" id="O26">
+      <attribute name="obj_pos">
+        <point val="6,13.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="5.15,7.65;13.35,14.35"/>
+      </attribute>
+      <attribute name="conn_endpoints">
+        <point val="6,13.5"/>
+        <point val="12.5,8.5"/>
+      </attribute>
+      <attribute name="numcp">
+        <int val="1"/>
+      </attribute>
+      <attribute name="end_arrow">
+        <enum val="3"/>
+      </attribute>
+      <attribute name="end_arrow_length">
+        <real val="0.8"/>
+      </attribute>
+      <attribute name="end_arrow_width">
+        <real val="0.8"/>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O27">
+      <attribute name="obj_pos">
+        <point val="6.5,10.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="4.582,9.7069;8.418,10.7069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#d.dims#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="6.5,10.5"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+  </layer>
+</diagram>

Documentation/Spec/email1.dia

@@ -0,0 +1,597 @@
+<?xml version="1.0"?>
+<diagram xmlns:dia="http://www.lysator.liu.se/~alla/dia/">
+  <diagramdata>
+    <attribute name="background">
+      <color val="#ffffff"/>
+    </attribute>
+    <attribute name="paper">
+      <composite type="paper">
+        <attribute name="name">
+          <string>#A4#</string>
+        </attribute>
+        <attribute name="tmargin">
+          <real val="2.82"/>
+        </attribute>
+        <attribute name="bmargin">
+          <real val="2.82"/>
+        </attribute>
+        <attribute name="lmargin">
+          <real val="2.82"/>
+        </attribute>
+        <attribute name="rmargin">
+          <real val="2.82"/>
+        </attribute>
+        <attribute name="is_portrait">
+          <boolean val="true"/>
+        </attribute>
+        <attribute name="scaling">
+          <real val="1"/>
+        </attribute>
+        <attribute name="fitto">
+          <boolean val="false"/>
+        </attribute>
+      </composite>
+    </attribute>
+  </diagramdata>
+  <layer name="Background" visible="true">
+    <object type="Standard - Box" version="0" id="O0">
+      <attribute name="obj_pos">
+        <point val="14.5,3"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="14.45,2.95;20.05,4.55"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="14.5,3"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="5.5"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O1">
+      <attribute name="obj_pos">
+        <point val="8,5.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="7.95,5.45;13.55,7.05"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="8,5.5"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="5.5"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O2">
+      <attribute name="obj_pos">
+        <point val="1.5,8"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="1.45,7.95;7.05,9.55"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="1.5,8"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="5.5"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O3">
+      <attribute name="obj_pos">
+        <point val="1.5,6.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="1.45,6.45;7.05,8.05"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="1.5,6.5"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="5.5"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O4">
+      <attribute name="obj_pos">
+        <point val="1.5,5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="1.45,4.95;7.05,6.55"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="1.5,5"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="5.5"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O5">
+      <attribute name="obj_pos">
+        <point val="1.5,9.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="1.45,9.45;7.05,11.05"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="1.5,9.5"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="5.5"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O6">
+      <attribute name="obj_pos">
+        <point val="8,4"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="7.95,3.95;13.55,5.55"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="8,4"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="5.5"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O7">
+      <attribute name="obj_pos">
+        <point val="8,7"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="7.95,6.95;13.55,8.55"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="8,7"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="5.5"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O8">
+      <attribute name="obj_pos">
+        <point val="8,8.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="7.95,8.45;13.55,10.05"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="8,8.5"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="5.5"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Line" version="0" id="O9">
+      <attribute name="obj_pos">
+        <point val="1.5,9.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="1.45,4.45;14.55,9.55"/>
+      </attribute>
+      <attribute name="conn_endpoints">
+        <point val="1.5,9.5"/>
+        <point val="14.5,4.5"/>
+      </attribute>
+      <attribute name="numcp">
+        <int val="1"/>
+      </attribute>
+      <connections>
+        <connection handle="0" to="O2" connection="5"/>
+        <connection handle="1" to="O0" connection="5"/>
+      </connections>
+    </object>
+    <object type="Standard - Text" version="0" id="O10">
+      <attribute name="obj_pos">
+        <point val="3.5,3"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="-4.478,2.25664;11.478,3.25664"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#Mailboxes, other structure#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="3.5,3"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O11">
+      <attribute name="obj_pos">
+        <point val="6.5,13.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="4.885,12.7566;8.115,13.7566"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#d.ref#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="6.5,13.5"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Line" version="0" id="O12">
+      <attribute name="obj_pos">
+        <point val="7.5,12.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="7.45,7.45;7.55,12.55"/>
+      </attribute>
+      <attribute name="conn_endpoints">
+        <point val="7.5,12.5"/>
+        <point val="7.5,7.5"/>
+      </attribute>
+      <attribute name="numcp">
+        <int val="1"/>
+      </attribute>
+    </object>
+    <object type="Standard - Line" version="0" id="O13">
+      <attribute name="obj_pos">
+        <point val="17.5,4.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="17.45,4.45;17.55,14.55"/>
+      </attribute>
+      <attribute name="conn_endpoints">
+        <point val="17.5,4.5"/>
+        <point val="17.5,14.5"/>
+      </attribute>
+      <attribute name="numcp">
+        <int val="1"/>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O14">
+      <attribute name="obj_pos">
+        <point val="14.5,5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="14.45,4.95;20.05,6.55"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="14.5,5"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="5.5"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O15">
+      <attribute name="obj_pos">
+        <point val="14.5,7"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="14.45,6.95;20.05,8.55"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="14.5,7"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="5.5"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O16">
+      <attribute name="obj_pos">
+        <point val="14.5,9"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="14.45,8.95;20.05,10.55"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="14.5,9"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="5.5"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O17">
+      <attribute name="obj_pos">
+        <point val="14.5,11"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="14.45,10.95;20.05,12.55"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="14.5,11"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="5.5"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O18">
+      <attribute name="obj_pos">
+        <point val="14.5,13"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="14.45,12.95;20.05,14.55"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="14.5,13"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="5.5"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O19">
+      <attribute name="obj_pos">
+        <point val="10.5,13"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="7.976,12.2566;13.024,13.2566"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#d.handle#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="10.5,13"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O20">
+      <attribute name="obj_pos">
+        <point val="18.5,6"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="18.5,5.25664;18.5,6.25664"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>##</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="18.5,6"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O21">
+      <attribute name="obj_pos">
+        <point val="20,5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="19.95,4.95;25.55,6.55"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="20,5"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="5.5"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O22">
+      <attribute name="obj_pos">
+        <point val="20,7"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="19.95,6.95;25.55,8.55"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="20,7"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="5.5"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O23">
+      <attribute name="obj_pos">
+        <point val="20,9"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="19.95,8.95;25.55,10.55"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="20,9"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="5.5"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O24">
+      <attribute name="obj_pos">
+        <point val="20,11"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="19.95,10.95;25.55,12.55"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="20,11"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="5.5"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O25">
+      <attribute name="obj_pos">
+        <point val="24,6"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="24,5.25664;24,6.25664"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>##</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="24,6"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+  </layer>
+</diagram>

Documentation/Spec/inheritparam.dia

@@ -0,0 +1,885 @@
+<?xml version="1.0"?>
+<diagram xmlns:dia="http://www.lysator.liu.se/~alla/dia/">
+  <diagramdata>
+    <attribute name="background">
+      <color val="#ffffff"/>
+    </attribute>
+    <attribute name="paper">
+      <composite type="paper">
+        <attribute name="name">
+          <string>#A4#</string>
+        </attribute>
+        <attribute name="tmargin">
+          <real val="2.82"/>
+        </attribute>
+        <attribute name="bmargin">
+          <real val="2.82"/>
+        </attribute>
+        <attribute name="lmargin">
+          <real val="2.82"/>
+        </attribute>
+        <attribute name="rmargin">
+          <real val="2.82"/>
+        </attribute>
+        <attribute name="is_portrait">
+          <boolean val="true"/>
+        </attribute>
+        <attribute name="scaling">
+          <real val="1"/>
+        </attribute>
+        <attribute name="fitto">
+          <boolean val="false"/>
+        </attribute>
+      </composite>
+    </attribute>
+  </diagramdata>
+  <layer name="Background" visible="true">
+    <object type="Standard - Box" version="0" id="O0">
+      <attribute name="obj_pos">
+        <point val="8,12.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="7.95,12.45;12.5,14.05"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="8,12.5"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="4.45"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Line" version="0" id="O1">
+      <attribute name="obj_pos">
+        <point val="14.225,2.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="14.175,2.45;14.275,13.55"/>
+      </attribute>
+      <attribute name="conn_endpoints">
+        <point val="14.225,2.5"/>
+        <point val="14.225,13.5"/>
+      </attribute>
+      <attribute name="numcp">
+        <int val="1"/>
+      </attribute>
+      <connections>
+        <connection handle="0" to="O2" connection="6"/>
+        <connection handle="1" to="O7" connection="1"/>
+      </connections>
+    </object>
+    <object type="Standard - Box" version="0" id="O2">
+      <attribute name="obj_pos">
+        <point val="12,1"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="11.95,0.95;16.5,2.55"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="12,1"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="4.45"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O3">
+      <attribute name="obj_pos">
+        <point val="12,3.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="11.95,3.45;16.5,5.05"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="12,3.5"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="4.45"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O4">
+      <attribute name="obj_pos">
+        <point val="12,6"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="11.95,5.95;16.5,7.55"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="12,6"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="4.45"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O5">
+      <attribute name="obj_pos">
+        <point val="12,8.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="11.95,8.45;16.5,10.05"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="12,8.5"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="4.45"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O6">
+      <attribute name="obj_pos">
+        <point val="12,11"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="11.95,10.95;16.5,12.55"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="12,11"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="4.45"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O7">
+      <attribute name="obj_pos">
+        <point val="12,13.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="11.95,13.45;16.5,15.05"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="12,13.5"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="4.45"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O8">
+      <attribute name="obj_pos">
+        <point val="2.5,12.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="2.45,12.45;7,14.05"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="2.5,12.5"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="4.45"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Line" version="0" id="O9">
+      <attribute name="obj_pos">
+        <point val="7,6"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="6.95,5.95;12.05,9.3"/>
+      </attribute>
+      <attribute name="conn_endpoints">
+        <point val="7,6"/>
+        <point val="12,9.25"/>
+      </attribute>
+      <attribute name="numcp">
+        <int val="1"/>
+      </attribute>
+      <connections>
+        <connection handle="1" to="O5" connection="3"/>
+      </connections>
+    </object>
+    <object type="Standard - Line" version="0" id="O10">
+      <attribute name="obj_pos">
+        <point val="4.725,5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="4.675,4.95;4.775,12.55"/>
+      </attribute>
+      <attribute name="conn_endpoints">
+        <point val="4.725,5"/>
+        <point val="4.725,12.5"/>
+      </attribute>
+      <attribute name="numcp">
+        <int val="1"/>
+      </attribute>
+      <connections>
+        <connection handle="0" to="O11" connection="1"/>
+        <connection handle="1" to="O8" connection="1"/>
+      </connections>
+    </object>
+    <object type="Standard - Box" version="0" id="O11">
+      <attribute name="obj_pos">
+        <point val="2.5,5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="2.45,4.95;7,6.55"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="2.5,5"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="4.45"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O12">
+      <attribute name="obj_pos">
+        <point val="2.5,7.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="2.45,7.45;7,9.05"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="2.5,7.5"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="4.45"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O13">
+      <attribute name="obj_pos">
+        <point val="2.5,10"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="2.45,9.95;7,11.55"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="2.5,10"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="4.45"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O14">
+      <attribute name="obj_pos">
+        <point val="17.5,6"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="17.45,5.95;22,7.55"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="17.5,6"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="4.45"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O15">
+      <attribute name="obj_pos">
+        <point val="17.5,11"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="17.45,10.95;22,12.55"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="17.5,11"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="4.45"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Line" version="0" id="O16">
+      <attribute name="obj_pos">
+        <point val="16.45,6.75"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="16.4,6.7;17.55,6.8"/>
+      </attribute>
+      <attribute name="conn_endpoints">
+        <point val="16.45,6.75"/>
+        <point val="17.5,6.75"/>
+      </attribute>
+      <attribute name="numcp">
+        <int val="1"/>
+      </attribute>
+      <connections>
+        <connection handle="0" to="O4" connection="4"/>
+        <connection handle="1" to="O14" connection="3"/>
+      </connections>
+    </object>
+    <object type="Standard - Line" version="0" id="O17">
+      <attribute name="obj_pos">
+        <point val="17.5,11.75"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="16.4,11.7;17.55,11.8"/>
+      </attribute>
+      <attribute name="conn_endpoints">
+        <point val="17.5,11.75"/>
+        <point val="16.45,11.75"/>
+      </attribute>
+      <attribute name="numcp">
+        <int val="1"/>
+      </attribute>
+      <connections>
+        <connection handle="0" to="O15" connection="3"/>
+        <connection handle="1" to="O6" connection="4"/>
+      </connections>
+    </object>
+    <object type="Standard - Line" version="0" id="O18">
+      <attribute name="obj_pos">
+        <point val="6.95,13.25"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="6.9,13.2;8.05,13.3"/>
+      </attribute>
+      <attribute name="conn_endpoints">
+        <point val="6.95,13.25"/>
+        <point val="8,13.25"/>
+      </attribute>
+      <attribute name="numcp">
+        <int val="1"/>
+      </attribute>
+      <connections>
+        <connection handle="0" to="O8" connection="4"/>
+        <connection handle="1" to="O0" connection="3"/>
+      </connections>
+    </object>
+    <object type="Standard - Text" version="0" id="O19">
+      <attribute name="obj_pos">
+        <point val="14,2"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="12.385,1.2069;15.615,2.2069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#start#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="14,2"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O20">
+      <attribute name="obj_pos">
+        <point val="14,7"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="12.385,6.2069;15.615,7.2069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#param#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="14,7"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O21">
+      <attribute name="obj_pos">
+        <point val="19.5,7"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="17.885,6.2069;21.115,7.2069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#value#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="19.5,7"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O22">
+      <attribute name="obj_pos">
+        <point val="14,9.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="13.597,8.7069;14.403,9.7069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#+#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="14,9.5"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O23">
+      <attribute name="obj_pos">
+        <point val="4.5,8.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="2.885,7.7069;6.115,8.7069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#param#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="4.5,8.5"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O24">
+      <attribute name="obj_pos">
+        <point val="4.5,13.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="2.885,12.7069;6.115,13.7069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#param#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="4.5,13.5"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O25">
+      <attribute name="obj_pos">
+        <point val="10,13.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="8.385,12.7069;11.615,13.7069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#value#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="10,13.5"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - BezierLine" version="0" id="O26">
+      <attribute name="obj_pos">
+        <point val="17,1"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="7,-1.5;18,22"/>
+      </attribute>
+      <attribute name="bez_points">
+        <point val="17,1"/>
+        <point val="16,21"/>
+        <point val="8,-0.5"/>
+        <point val="8,7"/>
+      </attribute>
+      <attribute name="corner_types">
+        <enum val="0"/>
+        <enum val="0"/>
+      </attribute>
+      <attribute name="line_width">
+        <real val="0.4"/>
+      </attribute>
+      <attribute name="line_style">
+        <enum val="4"/>
+      </attribute>
+      <attribute name="end_arrow">
+        <enum val="3"/>
+      </attribute>
+      <attribute name="end_arrow_length">
+        <real val="0.8"/>
+      </attribute>
+      <attribute name="end_arrow_width">
+        <real val="0.8"/>
+      </attribute>
+    </object>
+    <object type="Standard - BezierLine" version="0" id="O27">
+      <attribute name="obj_pos">
+        <point val="8,7.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="6.5,-1.49012e-08;18.5,23"/>
+      </attribute>
+      <attribute name="bez_points">
+        <point val="8,7.5"/>
+        <point val="7.5,22"/>
+        <point val="17.05,1"/>
+        <point val="17.5,9"/>
+      </attribute>
+      <attribute name="corner_types">
+        <enum val="0"/>
+        <enum val="0"/>
+      </attribute>
+      <attribute name="line_width">
+        <real val="0.4"/>
+      </attribute>
+      <attribute name="line_style">
+        <enum val="4"/>
+      </attribute>
+      <attribute name="end_arrow">
+        <enum val="3"/>
+      </attribute>
+      <attribute name="end_arrow_length">
+        <real val="0.8"/>
+      </attribute>
+      <attribute name="end_arrow_width">
+        <real val="0.8"/>
+      </attribute>
+    </object>
+    <object type="Standard - BezierLine" version="0" id="O28">
+      <attribute name="obj_pos">
+        <point val="17.5,9"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="16.5,8;18.5,15.5"/>
+      </attribute>
+      <attribute name="bez_points">
+        <point val="17.5,9"/>
+        <point val="17.5,12.5"/>
+        <point val="17.5,14.5"/>
+        <point val="17.5,14.5"/>
+      </attribute>
+      <attribute name="corner_types">
+        <enum val="0"/>
+        <enum val="0"/>
+      </attribute>
+      <attribute name="line_width">
+        <real val="0.4"/>
+      </attribute>
+      <attribute name="line_style">
+        <enum val="4"/>
+      </attribute>
+      <attribute name="end_arrow">
+        <enum val="3"/>
+      </attribute>
+      <attribute name="end_arrow_length">
+        <real val="0.8"/>
+      </attribute>
+      <attribute name="end_arrow_width">
+        <real val="0.8"/>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O29">
+      <attribute name="obj_pos">
+        <point val="20,1.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="17.173,0.706897;22.827,1.7069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#Traversal#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="20,1.5"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Line" version="0" id="O30">
+      <attribute name="obj_pos">
+        <point val="2.5,0.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="2.45,0.45;2.55,3.55"/>
+      </attribute>
+      <attribute name="conn_endpoints">
+        <point val="2.5,0.5"/>
+        <point val="2.5,3.5"/>
+      </attribute>
+      <attribute name="numcp">
+        <int val="1"/>
+      </attribute>
+    </object>
+    <object type="Standard - Line" version="0" id="O31">
+      <attribute name="obj_pos">
+        <point val="2.5,0.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="2.45,0.45;8.55,0.55"/>
+      </attribute>
+      <attribute name="conn_endpoints">
+        <point val="2.5,0.5"/>
+        <point val="8.5,0.5"/>
+      </attribute>
+      <attribute name="numcp">
+        <int val="1"/>
+      </attribute>
+    </object>
+    <object type="Standard - Line" version="0" id="O32">
+      <attribute name="obj_pos">
+        <point val="2.5,0.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="2.45,0.45;8.55,3.55"/>
+      </attribute>
+      <attribute name="conn_endpoints">
+        <point val="2.5,0.5"/>
+        <point val="8.5,3.5"/>
+      </attribute>
+      <attribute name="numcp">
+        <int val="1"/>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O33">
+      <attribute name="obj_pos">
+        <point val="9,1.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="7.991,0.706897;10.009,1.7069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#d.1#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="9,1.5"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O34">
+      <attribute name="obj_pos">
+        <point val="2.5,4"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="1.491,3.2069;3.509,4.2069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#d.2#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="2.5,4"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O35">
+      <attribute name="obj_pos">
+        <point val="9,4"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="7.991,3.2069;10.009,4.2069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#d.3#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="9,4"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+  </layer>
+</diagram>

Documentation/Spec/rasterspec.dia

@@ -0,0 +1,678 @@
+<?xml version="1.0"?>
+<diagram xmlns:dia="http://www.lysator.liu.se/~alla/dia/">
+  <diagramdata>
+    <attribute name="background">
+      <color val="#ffffff"/>
+    </attribute>
+    <attribute name="paper">
+      <composite type="paper">
+        <attribute name="name">
+          <string>#A4#</string>
+        </attribute>
+        <attribute name="tmargin">
+          <real val="2.82"/>
+        </attribute>
+        <attribute name="bmargin">
+          <real val="2.82"/>
+        </attribute>
+        <attribute name="lmargin">
+          <real val="2.82"/>
+        </attribute>
+        <attribute name="rmargin">
+          <real val="2.82"/>
+        </attribute>
+        <attribute name="is_portrait">
+          <boolean val="true"/>
+        </attribute>
+        <attribute name="scaling">
+          <real val="1"/>
+        </attribute>
+        <attribute name="fitto">
+          <boolean val="false"/>
+        </attribute>
+      </composite>
+    </attribute>
+  </diagramdata>
+  <layer name="Background" visible="true">
+    <object type="Standard - Box" version="0" id="O0">
+      <attribute name="obj_pos">
+        <point val="0,1"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="-0.05,0.95;4.5,2.55"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="0,1"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="4.45"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O1">
+      <attribute name="obj_pos">
+        <point val="6,1"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="5.95,0.95;10.5,2.55"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="6,1"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="4.45"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O2">
+      <attribute name="obj_pos">
+        <point val="6,3.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="5.95,3.45;10.5,5.05"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="6,3.5"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="4.45"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O3">
+      <attribute name="obj_pos">
+        <point val="6,6"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="5.95,5.95;10.5,7.55"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="6,6"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="4.45"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O4">
+      <attribute name="obj_pos">
+        <point val="12,3.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="11.95,3.45;16.5,5.05"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="12,3.5"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="4.45"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O5">
+      <attribute name="obj_pos">
+        <point val="18,3.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="17.95,3.45;22.5,5.05"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="18,3.5"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="4.45"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Box" version="0" id="O6">
+      <attribute name="obj_pos">
+        <point val="12,6"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="11.95,5.95;16.5,7.55"/>
+      </attribute>
+      <attribute name="elem_corner">
+        <point val="12,6"/>
+      </attribute>
+      <attribute name="elem_width">
+        <real val="4.45"/>
+      </attribute>
+      <attribute name="elem_height">
+        <real val="1.5"/>
+      </attribute>
+      <attribute name="show_background">
+        <boolean val="true"/>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O7">
+      <attribute name="obj_pos">
+        <point val="2,2"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="-0.2816,1.36552;4.2816,2.16552"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#vanishing#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="0.8"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="2,2"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O8">
+      <attribute name="obj_pos">
+        <point val="8,2"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="8,1.2069;8,2.2069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>##</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="8,2"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O9">
+      <attribute name="obj_pos">
+        <point val="8,4.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="8,3.7069;8,4.7069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>##</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="8,4.5"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O10">
+      <attribute name="obj_pos">
+        <point val="8,4.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="6.991,3.7069;9.009,4.7069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#gap#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="8,4.5"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O11">
+      <attribute name="obj_pos">
+        <point val="14,4.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="13.597,3.7069;14.403,4.7069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#5#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="14,4.5"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O12">
+      <attribute name="obj_pos">
+        <point val="20,4.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="19.597,3.7069;20.403,4.7069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#5#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="20,4.5"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O13">
+      <attribute name="obj_pos">
+        <point val="8,7"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="6.385,6.2069;9.615,7.2069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#depth#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="8,7"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O14">
+      <attribute name="obj_pos">
+        <point val="14,7"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="13.597,6.2069;14.403,7.2069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#6#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="14,7"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Line" version="0" id="O15">
+      <attribute name="obj_pos">
+        <point val="4.5,2"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="3.65,1.15;6.85,2.85"/>
+      </attribute>
+      <attribute name="conn_endpoints">
+        <point val="4.5,2"/>
+        <point val="6,2"/>
+      </attribute>
+      <attribute name="numcp">
+        <int val="1"/>
+      </attribute>
+      <attribute name="end_arrow">
+        <enum val="3"/>
+      </attribute>
+      <attribute name="end_arrow_length">
+        <real val="0.8"/>
+      </attribute>
+      <attribute name="end_arrow_width">
+        <real val="0.8"/>
+      </attribute>
+    </object>
+    <object type="Standard - Line" version="0" id="O16">
+      <attribute name="obj_pos">
+        <point val="8.225,2.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="7.375,1.65;9.075,4.35"/>
+      </attribute>
+      <attribute name="conn_endpoints">
+        <point val="8.225,2.5"/>
+        <point val="8.225,3.5"/>
+      </attribute>
+      <attribute name="numcp">
+        <int val="1"/>
+      </attribute>
+      <attribute name="end_arrow">
+        <enum val="3"/>
+      </attribute>
+      <attribute name="end_arrow_length">
+        <real val="0.8"/>
+      </attribute>
+      <attribute name="end_arrow_width">
+        <real val="0.8"/>
+      </attribute>
+      <connections>
+        <connection handle="0" to="O1" connection="6"/>
+        <connection handle="1" to="O2" connection="1"/>
+      </connections>
+    </object>
+    <object type="Standard - Line" version="0" id="O17">
+      <attribute name="obj_pos">
+        <point val="8.225,5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="7.375,4.15;9.075,6.85"/>
+      </attribute>
+      <attribute name="conn_endpoints">
+        <point val="8.225,5"/>
+        <point val="8.225,6"/>
+      </attribute>
+      <attribute name="numcp">
+        <int val="1"/>
+      </attribute>
+      <attribute name="end_arrow">
+        <enum val="3"/>
+      </attribute>
+      <attribute name="end_arrow_length">
+        <real val="0.8"/>
+      </attribute>
+      <attribute name="end_arrow_width">
+        <real val="0.8"/>
+      </attribute>
+      <connections>
+        <connection handle="0" to="O2" connection="6"/>
+        <connection handle="1" to="O3" connection="1"/>
+      </connections>
+    </object>
+    <object type="Standard - Line" version="0" id="O18">
+      <attribute name="obj_pos">
+        <point val="10.5,4.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="9.65,3.65;12.85,5.35"/>
+      </attribute>
+      <attribute name="conn_endpoints">
+        <point val="10.5,4.5"/>
+        <point val="12,4.5"/>
+      </attribute>
+      <attribute name="numcp">
+        <int val="1"/>
+      </attribute>
+      <attribute name="end_arrow">
+        <enum val="3"/>
+      </attribute>
+      <attribute name="end_arrow_length">
+        <real val="0.8"/>
+      </attribute>
+      <attribute name="end_arrow_width">
+        <real val="0.8"/>
+      </attribute>
+    </object>
+    <object type="Standard - Line" version="0" id="O19">
+      <attribute name="obj_pos">
+        <point val="10.5,7"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="9.65,6.15;12.85,7.85"/>
+      </attribute>
+      <attribute name="conn_endpoints">
+        <point val="10.5,7"/>
+        <point val="12,7"/>
+      </attribute>
+      <attribute name="numcp">
+        <int val="1"/>
+      </attribute>
+      <attribute name="end_arrow">
+        <enum val="3"/>
+      </attribute>
+      <attribute name="end_arrow_length">
+        <real val="0.8"/>
+      </attribute>
+      <attribute name="end_arrow_width">
+        <real val="0.8"/>
+      </attribute>
+    </object>
+    <object type="Standard - Line" version="0" id="O20">
+      <attribute name="obj_pos">
+        <point val="16.5,4.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="15.65,3.65;18.85,5.35"/>
+      </attribute>
+      <attribute name="conn_endpoints">
+        <point val="16.5,4.5"/>
+        <point val="18,4.5"/>
+      </attribute>
+      <attribute name="numcp">
+        <int val="1"/>
+      </attribute>
+      <attribute name="end_arrow">
+        <enum val="3"/>
+      </attribute>
+      <attribute name="end_arrow_length">
+        <real val="0.8"/>
+      </attribute>
+      <attribute name="end_arrow_width">
+        <real val="0.8"/>
+      </attribute>
+    </object>
+    <object type="Standard - Line" version="0" id="O21">
+      <attribute name="obj_pos">
+        <point val="2.5,9"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="1.65,8.15;12.35,9.85"/>
+      </attribute>
+      <attribute name="conn_endpoints">
+        <point val="2.5,9"/>
+        <point val="11.5,9"/>
+      </attribute>
+      <attribute name="numcp">
+        <int val="1"/>
+      </attribute>
+      <attribute name="end_arrow">
+        <enum val="3"/>
+      </attribute>
+      <attribute name="end_arrow_length">
+        <real val="0.8"/>
+      </attribute>
+      <attribute name="end_arrow_width">
+        <real val="0.8"/>
+      </attribute>
+    </object>
+    <object type="Standard - Line" version="0" id="O22">
+      <attribute name="obj_pos">
+        <point val="2.5,3.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="1.65,2.65;3.35,8.85"/>
+      </attribute>
+      <attribute name="conn_endpoints">
+        <point val="2.5,3.5"/>
+        <point val="2.5,8"/>
+      </attribute>
+      <attribute name="numcp">
+        <int val="1"/>
+      </attribute>
+      <attribute name="end_arrow">
+        <enum val="3"/>
+      </attribute>
+      <attribute name="end_arrow_length">
+        <real val="0.8"/>
+      </attribute>
+      <attribute name="end_arrow_width">
+        <real val="0.8"/>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O23">
+      <attribute name="obj_pos">
+        <point val="3.5,5.5"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="2.491,4.7069;4.509,5.7069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#d.2#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="3.5,5.5"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+    <object type="Standard - Text" version="0" id="O24">
+      <attribute name="obj_pos">
+        <point val="5.5,10"/>
+      </attribute>
+      <attribute name="obj_bb">
+        <rectangle val="4.491,9.2069;6.509,10.2069"/>
+      </attribute>
+      <attribute name="text">
+        <composite type="text">
+          <attribute name="string">
+            <string>#d.1#</string>
+          </attribute>
+          <attribute name="font">
+            <font name="Courier"/>
+          </attribute>
+          <attribute name="height">
+            <real val="1"/>
+          </attribute>
+          <attribute name="pos">
+            <point val="5.5,10"/>
+          </attribute>
+          <attribute name="color">
+            <color val="#000000"/>
+          </attribute>
+          <attribute name="alignment">
+            <enum val="1"/>
+          </attribute>
+        </composite>
+      </attribute>
+    </object>
+  </layer>
+</diagram>

Documentation/Syntaxless/synt.wml

@@ -0,0 +1,100 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
+   "http://www.w3.org/TR/html4/strict.dtd"> 
+<!--
+	NOTE! This file uses WML 2.0.1
+
+	PLEASE PLEASE PLEASE don't edit .HTML. Edit .WML!!!! Actually,
+	it's more important for you since your changes will be LOST FOREVER
+	if you edit the .HTML files.
+ -->
+
+<html>
+ <head>
+  <title>The case for syntaxless languages</title>
+#include '../wmlinc/article.wml'
+ </head>
+ <body>
+{: [[s/(?<!>)\b(d\.+\w+)/<code>\1<\/code>/g]]
+<H1>The case for syntaxless languages</H1>
+<pre>$Id: synt.wml,v 1.1 2000/09/17 23:50:51 tjl Exp $</pre>
+<toc>
+
+<p>
+A manuscript-in-progress about syntaxless languages such as Clang.
+Intended for eventual publication in an academic journal.
+
+<warn>
+
+<h2>Introduction</h2>
+
+<h2>Computational structures</h2>
+
+<p>
+The most pervasive computing paradigm of today is that of
+directories and files, and of programs written as text.
+All the dominant platforms, Linux/Unix, Mac and Windows are based
+on the same fundamental structure.
+Indeed, the structure is so pervasive that it is difficult
+for many people to even imagine a different world. 
+
+<p>
+However, a different world is actually not even difficult to 
+define and implement: choosing a different data model for implementing
+an operating system, for example, is completely feasible,
+as shown e.g. by XXX.
+
+<p>
+In our work, we focus on the ZigZag structure, which is one alternative
+to the directories-files-text model.
+In ZigZag, data is contained in cells which are bidirectionally
+interconnected in a flexible, multidimensional structure.
+
+
+<h2>Parsing, symbol tables and integrated development environments</h2>
+
+<p>
+<small>We will probably need to use that term in every
+paper we write ;) ;)</small>
+
+<p>
+Today's computer languages are, with few exceptions, expressed as text.
+Even the use of the word computer <em>language</em> itself conveys
+the expectation that computer languages, like human languages,
+is expressible in a linear form.
+
+<p>
+In this context, a parser and symbol tables are
+an essential ingredient of a compiler; and that a language
+definition requires defining a Backus-Naur form syntax and
+namespaces for various identifiers.
+
+<p>
+Likewise, it is often found that using an editor which understands
+the language syntax and is able to suggest completions to e.g. method
+names is almost irreplaceable. Especially important is the ability
+to jump from a use of a symbol to the point in the code where
+the symbol was defined.
+
+<p>
+However, human language is expressible as one-dimensional
+because of a simple constraint in speech: time. When a language
+is spoken, a sequential form is a requirement. 
+
+<p>
+Computer languages try to mimic human languages in several ways.
+
+<h2>Syntaxless languages</h2>
+
+<p>
+A syntaxless language is based on there being a richer underlying
+structure than a simple text stream. 
+
+
+<h2></h2>
+
+:}
+</body>
+</html>
+<!--
+	vim: set syntax=html :
+-->

Documentation/UsersGuide/Makefile

@@ -0,0 +1,15 @@
+# DIAGRAMS=linkorder.png beamorder.png
+
+all : ug.html ug-ns4.html newug.html newug-ns4.html
+
+ugdep = ug.wml ../keybindings.wml ../wmlinc/article.wml ../wmlinc/common.wml $(DIAGRAMS)
+ug.html : $(ugdep)
+ug-ns4.html: $(ugdep)
+
+newugdep = newug.wml ../keybindings.wml ../wmlinc/catart.wml  ../wmlinc/common.wml $(DIAGRAMS)
+newug.html: $(newugdep)
+newug-ns4.html: $(newugdep)
+
+include ../lib.mk
+
+