$Id: ug.html,v 1.16 2002/12/19 17:36:39 Vegai Exp $
| Tuomas Lukka
Dept. of Mathematical Information Technology
University of Jyväskylä
This is the first attempt at an user's guide for GZigZag. It is not yet complete and not a good tutorial but we will try to work on it. Patches are gladly accepted! This is work-in-progress: if there are any unclear parts, feel free to ask me to clarify things.
Note that this document contains some formatting that is best rendered
using a true CSS1 standard-compliant browser such as Mozilla; however,
it should work reasonably well with any browser that can at least ignore
CSS that it doesn't understand. Unfortunately, Netscape Navigator 4.7,
for example, doesn't. Well, that's life...
A non-CSS version exists: you can try by compiling this document from its WML version with some switches.. (if you came here through the WWW, there should be an alternate link on the referring page. However, I like the pretty rendering by Mozilla so much that that's still the default.
GZigZag is a free implementation of Ted Nelson's ZigZag structure. The ZigZag structure is a revolutionary new way of storing information in a computer, in that it provides a clear, extensible structure that can be orthogonally laid over existing information.
This document attempts to help users to get started with GZigZag.
We start at the point where the user has gotten the program to start;
to get to that point, read the other documentation, including
Note that this document does not attempt to cover designing sensible
structures: the "Gentle Introduction" document is for that purpose.
Here we only explain how to use the GZigZag implementation of the structure.
GZigZag is a moving target: we will try our best to keep this document up to date but sometimes it will simply be forgotten and be out of date. Please notify us if this happens.
GZigZag currently stores data in directories, in which there is one file per dimension and one or two extra files for the contents of the cells.
In the new, cached and explicit model, the data is loaded at startup and stored in memory until it is explicitly saved. Pressing ctrl-S saves the changes. And indeed, in GZigZag, it is only the changes that are saved: like CVS, GZigZag stores all the previous saved versions implicitly as well (XXX Because of timestamp problems, not usable yet).
The initial display of two windows next to each other. To fit them in this document, they have been horizontally resized but otherwise the view is exactly what you should get when starting GZigZag.
The first figure shows the two windows next to each other that show
up when starting GZigZag on an empty space.
There are two cursors, the green and the blue cursor, which are
seen on the same cell, the home cell. From the home cell downwards
d.2) is the system list, which contains
metainformation about the structure as well as keybindings, which
we shall return to later.
Let's move the blue cursor that defines the center of the right-hand window down three steps. There are three different ways to achieve this: either clicking on the "AllFlobViews" cell in the right-hand window or by pressing the arrow down key thrice, or (probably the most counterintuitive at first), pressing the comma (,) key thrice. This moves the view to the one shown in the next figure. If your machine is fast enough, it should animate between each step in order to better show how the cells move around.
The right-hand window, after moving the cursor down three step. Both cursors are shown in both views, but moving the blue cursor has moved the center of the right-side view with it.
The last way is actually the recommended way since it allows you to keep your hands on the main area of the keyboard at all times: mouse input is not needed in GZigZag. The direction keys for the X and Y directions are i, j, l and ',' for the right-hand view and e, s, f and c for the left-hand view. If you look at the keyboard, you'll see that they are arranged in two diamond patterns on the keyboard, one for the left and one for the right hand to use.
If you look at the upper left-hand corner of the windows, you'll see
that X and Y are not the only dimensions here: there is also a third
dimension, Z, on which
d.3 is shown by default.
A place in the default structure where
d.3 is used can be found
by moving two steps right and one down from "AllFlobViews".
The depth cell is connected to other cells poswards on
The keys to move the right-hand view along the Z axis are k for poswards
and K (shift-k) for negwards.
A place where the third dimension shown is used, as discussed in the text.
There are various different views to the structure, press 'v' or shift-V to cycle through them in either window.
Before going on, you should train yourself to use these keys to move around in the structure. The direction keys will be used in many places later on in this guide, since they also form a vital part of the commands.
We shall start from the home cell.
Press 'n' (for "New cell") and 'l' (the direction key discussed above) and a new cell is created left of the blue cursor:
The same would work for the other view, you just need to use the direction keys for the green cursor after the "n" command. For practice, move to the new cell (press 'l') and press 'n' 'l', 'n' 'j', 'n' 'i' and 'n' ',' to create new cells on all sides of the new cells. Note that when creating the new cell leftwards, it is inserted between the first new cell and the home cell:
Now, press Tab and type in some text:
Tab moved you to the text editing mode which is pretty much like familiar text entry mode in other systems: the arrow keys move the insertion cursor and typing a character inserts it. Press Tab again to move out of text edit mode, and the insertion cursor vanishes. (NOTE: one planned feature is to have the background change when in the edit mode - these pictures were taken when this did not yet happen).
Try putting more text into the other cells.
Now we get to the most important part of ZigZag: making actual structures. There are actually several different ways of connecting cells but we shall only cover one because there's no time to write this user's guide completely yet.
The way to connect two cells is to move the cursor of the left-hand view (green) and the right-hand view (blue) on the two cells, press '/' (slash) and a direction to connect the two cells in. Connect will fail if either of the two cells is connected in that direction already, except if one of them is alone in that dimension, in which case it is inserted next to the other one.
In this situation, pressing '/' ',' or, equivalently, '/' 'e' results in
Hopping is a structural operation where cells are reorganized along a rank. It's easiest to figure out if you try it: press 'h' and a direction key.
Another structural operation that can be very useful is the alpha-shear, which changes a connection from the current cell to another one in the same rank.
It is used by typing 'a' and two directions: first the connection and then the direction into which the connection is to be moved.
One more editing operation which helps a lot in making the structure work the way you want it to. Press '%' (percent) to exchange the connections of the two accursed cells in the visible X and Y dimensions. No other connections (Z or invisible) are touched.
Cloning is an important structural operation in GZigZag,
as explained in the Gentle Introduction.
Basically, a clone of a cell is a cell poswards from that
d.clone, but with the special property that their
contents are implied to be the same. Cloning is visually
shown by GZigZag by coloring the clones yellow and the original
A clone of a cell is made by placing the right or left cursor
on the cell and pressing 't' or shift-'t', respectively, and
a direction in which to place the clone.
Pressing shift-T 'l' creates a clone of the left (green) cursor and places it right of the right-side (blue) cursor:
In this section, we explain briefly what the system list is, and what you can do with it.
Basically, the system list contains information for the user interface of GZigZag, i.e. the types of views, keybindings etc. It is possible to configure GZigZag to look like something completely different but you must act carefully: it's fairly easy to accomplish something like the following:
Hmm, I want to rebind the keys completely. So let's delete the previous binding list (click) and then I'll start making the new bindings list (click.. click.... click....) oops, it's not responding! Right, I just deleted the keybindings list so of course it will not do anything when I press a key. Duh!
So remember that any changes to the system list are immediately reflected in the behaviour of the user interface. At some point we will probably create a mechanism for making delayed changes that you can commit all at once but this is not yet in place.
The system list starts at the home cell of the space and continues on
d.system, but for your convenience those cells you will most likely want to
use are cloned to a
d.2 rank starting from the home cell. The
is freely modifiable but changing the text in any of the system list cells,
or breaking the
d.system rank can lead to dire consequences and you probably
shouldn't do that. At a later date, the system list will probably be locked
The cells on the system list simply enumerate the functions: the
actual cells that describe whatever are connected to the system list
DimLists system list cell has connected to it on
a cyclical rank on
d.2, the dimension list.
This list contains the names of dimensions that the views
will cycle through when you press X, Y, Z (possibly with
Adding a dimension simply involves creating a new cell and typing the name into that cell. Likewise, deleting a cell will delete the dimension from the list (but not currently the connections along that dimension). NOTE: don't rotate to an empty cell: this will possibly cause problems: at the very least, a raster error.
The dimension cursors of the different views are a variety of pink shades. These dimension selectors of the different views are actually generic cursors so it would be possible to have different dimension lists for each X, Y and Z of each view but at the moment it's not possible to repoint them to a different list except by trickery. We will probably provide a mechanism for this.
The views are defined on three different cells in the system list:
These cells have different functions.
The windows cycle through different views by moving in the
Views, much like the dimensions are
cycled on the list below
The cells below
Views describe one particular
The cells below
Views are actually clones of
AllViews that actually give those
views' parameters. For instance, the Vanishing and StretchVanishing
rasters use the same Java code but have different parameters
in the structure below
The structure below
AllViews is simple:
it is a list of the clonable cells (which name the views, but
the name is just decoration for the user: the real information
is in the structural operation of cloning), which are
d.1 to the structure that actually defines the view.
The defining cells are structure along the ZOb structure, explained better elsewhere (XXX).
Not all views in
AllViews are by default cloned to the
list for two reasons: first, there are too many views to just cycle
through, and second: some are not yet very stable or useful.
Experimentation with them is encouraged, though.
is similar to
in that it also contains a list of cellviews, i.e. how to render
This is because currently there are not enough different cellviews
that having a separate list of more possibilities is not necessary.
$Id: ug.html,v 1.16 2002/12/19 17:36:39 Vegai Exp $
These are still being discussed and are not yet frozen. Note that there is a panic button: if there is no binding for ESC, it invokes undo.
|Ctrl-S||Commit the current changes to disk.|
|ijl,kK||Up-left-right-down-Z+-Z- in view 1.|
|esfcdD||Up-left-right-down-Z+-Z- in view 0.|
|n dir||Create a new cell in given direction|
|b dir||Break a connection in given direction|
|h dir||Hop the accursed cell in the given direction. Hopping means simply switching the places of the accursed and the indicated cells in that rank, no other ranks are affected by the operation.|
|xyz||Show next dimension on list on X/Y/Z in view 1|
|Alt-xyz||Show previous dimension on list on X/Y/Z in view 1|
|XYZ||Show next dimension on list on X/Y/Z in view 0|
|Alt-Shift-XYZ||Show previous dimension on list on X/Y/Z in view 0|
|/ dir||Connect the center cells of the right and left views in the given direction, if no connections will be broken by this.|
|~||Exchange the cursor positions of the two views (no other view parameters are changed).|
|Delete||Delete the center cell of view 1 and move the cursor. Cursor move tries following directions in order: X-, X+, Y-, Y+, Z-, Z+ and finally goes to home cell.|
|m||Mark or unmark the cell in view 1|
|Enter||Execute cell in view 0, with the cell in view 1 as parameter|
|v||Change raster in view 1.|
|V||Change raster in view 0.|
|Alt-v||Change raster in view 1 backwards.|
|Alt-V||Change raster in view 0 backwards.|
|Home||Go home: move view 1 cursor to homecell.|
|Esc||Move both views to home and reset dimensions to first three dimensions on first dimlist.|
|0123456789||Insert the given number into the number insert buffer for cell IDs.|
|g||Move view 1 to cell whose ID number was in buffer|
|G||Move view 0 to cell whose ID number was in buffer|
|Backspace||Remove one number from the number insert buffer|
|t dir||Clone the view 1 cursor to given direction (may be in either view).|
|T dir||Clone the view 0 cursor to given direction (may be in either view).|
|%||Exchange the X and Y connections of the two accursed cells with each other.|
|o||Go to original (rootclone, cell from which accursed cell was cloned) in view 1.|
|O||Go to original (rootclone, cell from which accursed cell was cloned) in view 0.|
|End dir||Move to te end of the rank in the given direction.|
|<||Set the cursor of the left-hand-view to the cell the right-hand view is pointing to.|
|>||Set the cursor of the right-hand-view to the cell the left-hand view is pointing to.|
|- dir||Connect the current view1 cursor into marked cells in given direction. Direction must be in view 1.|
|Alt-c||Switch into "curseling" (cursor selection) mode (see below).|
|a dir dir||Monochug: change one connection. See above.|
|Esc or Tab||Switch off text edit mode|
|Delete||Delete one character after cursor|
|Backspace||Delete one character before cursor|
|Left, Right||Move the cursor within the current cell|
|Home||Move the cursor to the beginning of the text in the current cell|
|End||Move the cursor to the end of the text in the current cell|
|Ctrl-A||Move the cursor to the beginning of the current line in the text of the current cell|
|Ctrl-E||Move the cursor to the end of the current line in the text of the current cell|
|Enter||Insert a line separator in the text before the cursor|
|any key producing a printable character||Insert the character in the text before the cursor|
As an intermediate for multiple cursors, there is a key binding mode for "curseling:" cursor selection. In the standard keybindings, Alt-c is used to go into this mode, which by default supports the following key bindings:
|Tab, Spacebar, Alt-c or Esc||Select this cursor, quit curseling mode.|
|Left, Right, jl||Select next/last cursor in system cursor list in view 1.|
|Up, Down, i,||Select next/last cursor positioned on the same cell in view 1.|
|sfec||Like Left/Right/Up/Down, operating on view 0.|
Note that you can create four additional cursors through executing the CreateCursors command, found in the action list, by centering the left view on it and hitting Enter.