GZigZag User's Guide

$Id: ug-ns4.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.

You are reading an ugly version of this document that doesn't use CSS to place floats nicely. Figures are shown in a very crude way. Get Mozilla and see the other version - it's MUCH better.


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 the README files. 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.

The save model

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).

Viewing and moving around

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 (poswards on 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 d.3. 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.

Editing the structure

This section does not give all the possible operations but tries to give a subset that will be sufficient. Marking is not discussed.

Creating new cells

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:

Entering text

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.

Connecting and disconnecting 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.

Cell exchange

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 cell on 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 light yellow. 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:

The system list

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 d.2 rank 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 by default.

The cells on the system list simply enumerate the functions: the actual cells that describe whatever are connected to the system list cells on d.1.

Dimension list

The DimLists system list cell has connected to it on d.1 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 shift/alt).

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: Views, AllViews and CellViews. These cells have different functions.

The windows cycle through different views by moving in the list below Views, much like the dimensions are cycled on the list below DimLists. The cells below Views describe one particular view.

The cells below Views are actually clones of cells below 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 AllViews.

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 connected on 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 main Views 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.

CellViews is similar to Views and AllViews in that it also contains a list of cellviews, i.e. how to render one cell. This is because currently there are not enough different cellviews that having a separate list of more possibilities is not necessary.



The keystrokes.

This is a list of (almost) all the currently available keystrokes in the default bindings. As explained above, it is simple to modify the bindings.

Default bindings for the orthogonal rasters

$Id: ug-ns4.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.

Key(s) Binding
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.

Text edit mode

Key(s) Binding
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

Curseling (Cursor selection)

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:

Key(s) Binding
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.